Importació massiva de comptes gestionats

La importació massiva carrega molts clients d'una vegada des d'un fitxer CSV. Cada fila és una de dues coses, segons la seva columna mode: un compte gestionat, un compte separat que aprovisiones per a un client, o un NIF propi, un NIF que dones d'alta al teu propi compte com a NIF addicional (l'app el mostra com a «NIF al meu compte»). Primer envies el fitxer a una previsualització, que classifica i tarifa cada fila sense escriure ni cobrar res, i després envies el mateix fitxer per aplicar-lo. Aquesta guia està escrita per al compte que aprovisiona, el proveïdor de comptes gestionats: mira comptes gestionats. Explica les tres operacions, el fitxer i les seves columnes, com el llegeix el parser, els límits, els estats per fila, la previsualització i el seu cost, què fa una segona importació del mateix fitxer, els clients que pots carregar-hi, l'aplicació i la seva idempotència, i què fa una clau de proves.

La importació és declarativa i no atòmica: el fitxer diu el que ha d'existir, cada fila que es pot aplicar s'aplica per separat i una fila que falla mai no desfà les altres. No té eina MCP ni opció de sèries de documents, com explica el final d'aquesta guia.

Les tres operacions

accounts:read i accounts:write són scopes privilegiats: * no els cobreix, i només els poden fer servir els comptes als quals hem concedit el privilegi de proveïdor. Sense el privilegi, o quan la persona que va emetre la clau ja no és titular ni administrador del teu compte, la resposta és 403 privileged_scope_required. La previsualització també necessita accounts:write, tot i que no escriu res. Cap de les tres rutes porta el segment {account}: el proveïdor és sempre el compte de la clau i l'entorn és el de la clau, i cap dels dos va a la petició.

L'ordre habitual és aquest: descarrega la plantilla, omple-la, envia-la a la previsualització, corregeix les files que surtin BLOCKED o ERROR i torna a previsualitzar, i després aplica els mateixos fitxers.

La petició

La previsualització i l'aplicació reben el mateix cos multipart/form-data.

Els dos fitxers són CSV, preferiblement en UTF-8, separats per comes, punt i coma o tabuladors, i de fins a 5 MB cadascun. El parser és més tolerant que la plantilla. Per previsualitzar el fitxer de l'exemple de més avall, envia només el fitxer de comptes:

curl -X POST https://api.factuarea.com/v1/accounts/imports/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -F "accounts_file=@accounts.csv"

No fixis Content-Type tu mateix: el teu client HTTP afegeix la capçalera multipart/form-data amb el seu boundary. Per aplicar, envia els mateixos camps a POST /v1/accounts/imports amb una Idempotency-Key.

Opcions

options va com a camps de formulari imbricats (options[send_email]=true) o com un únic camp JSON (options={"send_email":true}), que és com un client OpenAPI serialitza un objecte a multipart/form-data. Un booleà accepta true, false, 1, 0, on, off, yes i no. Qualsevol altra clau respon 422 invalid_param_value, així que una opció mal escrita mai no s'ignora en silenci.

El fitxer de comptes

El fitxer de comptes té una fila de capçalera i una fila per compte gestionat o per NIF propi, fins a 100. Una fila porta un NIF, i un NIF apareix una sola vegada al fitxer.

La plantilla

GET /v1/accounts/imports/template retorna text/csv com a adjunt amb el nom plantilla-importacion-cuentas.csv. És la mateixa per a tots els proveïdors i no llegeix res del teu compte. El fitxer és UTF-8 amb marca d'ordre de bytes (BOM), ; com a separador i fi de línia CRLF, que és el que un full de càlcul en castellà obre bé. Porta la fila de capçalera i una fila d'exemple:

mode;external_ref;plan;tax_id;legal_name;address;postal_code;city;province;country_code;owner_email;display_name;language;access_level
# ejemplo: managed_account;CLIENTE-0001;empresario;B12345674;Cliente Ejemplo SL;Calle Mayor 1;28013;Madrid;Madrid;ES;titular@example.com;Cliente Ejemplo;es;operate

La primera cel·la de la fila d'exemple comença per # ejemplo, i la importació ignora sempre una fila així. Sense aquesta marca seria una fila managed_account vàlida, així que treu-la només quan ho pretenguis. El conjunt de columnes és tancat: una columna que no és a la plantilla deixa cada fila en ERROR en aquesta columna, i el mateix fa una columna que apareix dues vegades.

Columnes

mode, plan, access_level i language es llegeixen en minúscules, i cada valor es retalla. Una cel·la buida compta com a absent. owner_email, language i access_level es comproven en la seva forma a totes les files, encara que la modalitat no les faci servir.

Com llegeix el fitxer el parser

El parser llegeix el que exporta un full de càlcul, així que és més tolerant que la plantilla. Decideix el tipus del fitxer pel seu contingut i mai pel seu nom ni la seva extensió.

El que no llegeix: un full de càlcul (.xlsx o .xls), un PDF, una imatge, un arxiu comprimit o qualsevol fitxer binari és 422 import_file_invalid encara que es digui .csv, i el mateix un fitxer sense fila de capçalera després del preàmbul, amb unes cometes dobles sense tancar o amb caràcters de control. Desa el full com a CSV abans de pujar-lo.

Límits

La mida i les files es comproven abans de llegir cap fila, així que quan en falla una no es classifica, escriu ni cobra res. Les files es compten sense la capçalera, les línies en blanc ni la fila d'exemple. Per carregar més de 100 clients, parteix el fitxer i envia les parts una darrere l'altra: cada part concilia per external_ref, així que pots tornar a enviar una part.

Estats per fila

La previsualització i l'aplicació classifiquen cada fila amb les mateixes regles i li donen un de cinc estats. Només els tres primers s'apliquen.

El code d'un WARNING diu què no ha canviat:

Les files es classifiquen en l'ordre del fitxer, així que les files vàlides anteriors a una esgoten els topalls que aquesta necessitaria: un fitxer amb més comptes nous de producció que el teu topall deixa les últimes BLOCKED. El code d'una fila és un motiu de l'informe de la importació i no sempre un codi del catàleg d'errors: els que tenen pàgina hi enllacen.

Errors per columna

Una fila mal formada surt ERROR amb code null i un objecte errors. La seva clau és la columna, o row per a un error de la fila sencera, i el seu valor és un missatge en castellà. L'objecte sempre hi és, i és {} quan la fila no té res malament. Una fila falla quan:

• una columna obligatòria està buida: mode, tax_id i legal_name, i external_ref i plan en un compte gestionat;
• mode no és own_nif ni managed_account;
• tax_id no és un NIF, CIF o NIE vàlid;
• plan no és emprendedor, empresario ni integral (enterprise queda BLOCKED, no és un error), o una fila own_nif el porta;
• language no és es, en ni ca, access_level no és none, view ni operate, o owner_email no és una adreça de correu;
• un text és més llarg que el seu màxim, o una legal_name o display_name d'un compte gestionat té menys de 2 caràcters;
• external_ref o tax_id ja va aparèixer en una fila anterior del fitxer: l'error va a la segona fila i a les següents;
• tax_id difereix del del compte gestionat que l'external_ref ja anomena;
• un compte gestionat nou de producció no té owner_email;
• la capçalera té una columna que no és a la plantilla o en repeteix una (l'error va en aquesta columna, a totes les files), o una fila té més valors que columnes té la capçalera (l'error va a row).

Un valor que el compte o el NIF rebutja mentre s'aplica la fila també és un ERROR, amb code null i el seu missatge a errors.row. Un error de la pròpia execució, com un error de la base de dades o de la passarel·la de pagament, és un ERROR amb code row_apply_failed. Cap dels dos atura la resta de la importació.

Codis dels errors

Cada entrada d'errors té el seu codi estable a error_codes, un objecte amb les mateixes claus: {columna: codi}. El missatge d'errors és en castellà i es pot reformular; el codi no es tradueix ni canvia, així que reacciona al codi, o tradueix-lo, i ensenya el missatge només a una persona. Igual que errors, sempre hi és i és {} quan la fila no té res malament; també en una importació creada abans que existís el camp. Una fila BLOCKED surt amb els dos objectes buits: el seu motiu és el code de la fila. El camp és additiu: errors no canvia.

La previsualització

POST /v1/accounts/imports/preview classifica i tarifa els fitxers sense cap efecte: no escriu res, no aprovisiona cap compte i no cobra res. Per tarifar les files només consulta Stripe, pel final del teu període de facturació i, per cada canvi de pla confirmat, l'import prorratejat d'aquest canvi, així que té el seu propi límit de 10 per minut. No necessita Idempotency-Key: és una consulta que fa servir POST perquè puja fitxers.

Pren aquest fitxer de comptes:

mode;external_ref;plan;tax_id;legal_name;address;postal_code;city;province;country_code;owner_email;display_name;language;access_level
managed_account;cliente-0042;empresario;B12345674;Talleres García SL;Calle Mayor 1;28013;Madrid;Madrid;ES;laura@talleresgarcia.example;Talleres García;es;operate
own_nif;;;B87654323;Distribuciones Norte SL;;;;;;;;;
managed_account;cliente-0043;emprendedor;A58818501;Panadería Sol SA;;;;;;marta@panaderiasol.example;;es;
managed_account;cliente-0044;emprendedor;;Gráficas Levante SL;;;;;;ivan@graficaslevante.example;;;

Té quatre files: un compte gestionat, un NIF propi, un segon compte gestionat que no cap al teu topall i un altre que va oblidar el seu NIF. La previsualització respon 200:

{
  "data": {
    "object": "managed_account_import_preview",
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "cliente-0042",
        "tax_id": "B12345674",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": "empresario",
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 3,
        "mode": "own_nif",
        "external_ref": null,
        "tax_id": "B87654323",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": null,
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 4,
        "mode": "managed_account",
        "external_ref": "cliente-0043",
        "tax_id": "A58818501",
        "status": "BLOCKED",
        "code": "managed_accounts_limit_reached",
        "errors": {},
        "error_codes": {},
        "plan": "emprendedor",
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 5,
        "mode": "managed_account",
        "external_ref": "cliente-0044",
        "tax_id": null,
        "status": "ERROR",
        "code": null,
        "errors": {
          "tax_id": "La columna tax_id es obligatoria: cada fila da de alta un NIF."
        },
        "error_codes": {
          "tax_id": "required"
        },
        "plan": null,
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      }
    ],
    "totals": {
      "total_rows": 4,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 1,
      "error": 1
    },
    "cost": {
      "currency": "EUR",
      "managed_account": {
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750
      },
      "own_nif": {
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750
      },
      "total": {
        "monthly_amount_cents": 5000,
        "proration_amount_cents": 2500
      }
    },
    "own_company_customers": null
  }
}

El cos té aquests camps:

I cada fila té aquests:

Què costa la importació

Cada fila porta monthly_amount_cents, l'import mensual que afegeix a la teva subscripció, i proration_amount_cents, el que cobra d'immediat aplicar-la pel que queda del teu període de facturació actual. cost els suma per a les files managed_account, per a les files own_nif i a total, amb la currency. Els imports són cèntims enters de base imposable, sense IVA: el nom de la clau diu la unitat.

A l'exemple, les dues files VALID afegeixen 3500 i 1500 cèntims al mes, 50,00 EUR, i aplicar el fitxer cobra d'immediat 2500 cèntims, 25,00 EUR. El prorrateig és la meitat de l'import mensual, com quan queda la meitat del teu període de facturació. Les files BLOCKED i ERROR no afegeixen res.

• Només compta el que es cobra. Només afegeixen import mensual les files noves que són VALID: els comptes gestionats nous, que es cobren a la subscripció managed-accounts del teu compte, i els NIF propis nous, que es cobren com a NIF addicionals. Una fila que ja existeix n'afegeix 0.
• Un canvi de pla confirmat només afegeix el seu prorrateig. Amb confirm_plan_changes, la fila d'un compte existent no té import mensual, però sí el prorrateig que cobraria un canvi de pla solt. Una pujada es cobra d'immediat. Una baixada té efecte al final del teu període i afegeix 0 ara.
• Algunes importacions costen 0. És 0 en una importació de proves, mentre el teu compte és al seu trial i quan al teu compte no se li cobra.
• L'aplicació cobra el que va anunciar la previsualització. El prorrateig anunciat per a un fitxer és el que cobra aplicar els mateixos fitxers. L'aplicació torna a classificar el fitxer en el moment en què l'envies, amb l'estat que tingui llavors el teu compte, així que una previsualització de fa hores pot diferir.

Files que surten BLOCKED

El code d'una fila BLOCKED és el motiu. Una fila BLOCKED no canvia res, ni camps ni pla.

Una fila que el domini rebutja mentre s'aplica, per exemple un topall que s'ha omplert entre la previsualització i l'aplicació, també queda BLOCKED, amb el codi públic d'aquest rebuig. Tracta un code que no coneguis com el motiu d'una fila BLOCKED.

Una fila own_nif necessita a més companies:write a la clau, a part d'accounts:write: sense ell, la fila és ERROR amb code insufficient_scope. Si la clau està limitada a alguns NIF, cada NIF que dona d'alta la importació s'afegeix a aquest límit, com quan dones d'alta un NIF amb una sola crida.

Importar una altra vegada el mateix fitxer

Aplicar una altra vegada el mateix fitxer mai no duplica un compte ni cobra dues vegades. L'external_ref d'una fila managed_account identifica el compte, i el tax_id identifica una fila own_nif. Una fila que anomena alguna cosa que ja existeix surt ALREADY_EXISTS, o WARNING o BLOCKED quan el que demana no es pot aplicar.

Què actualitza una segona importació

Només s'actualitza una llista de camps, i només mentre el compte no estigui reclamat: display_name (el nom visible, que és també el nom del compte i del seu NIF), language, legal_name, address, postal_code, city, province i country_code. Un camp canvia només quan la seva cel·la té valor, i un valor igual a l'actual no es reescriu. Tota la resta queda fora del seu abast:

• El NIF d'un compte existent no pot canviar: un tax_id diferent és un ERROR.
• El nivell d'accés mai canvia. Un nivell inferior al fitxer és un WARNING i un de superior és BLOCKED.
• El pla canvia només com diu el paràgraf següent.

Una fila que demana un pla diferent sobre un compte existent és WARNING plan_change_not_confirmed i no canvia res, tret que enviïs confirm_plan_changes. Amb ella, el canvi s'aplica quan encara pagues el compte, el teu nivell sobre ell és operate i no té contracte enterprise. Si no, la fila és BLOCKED amb plan_change_not_paid_by_provider, plan_change_requires_operate o managed_account_plan_not_self_serve. El canvi es tarifa com un canvi de pla solt. Si el perfil es va actualitzar i el canvi de pla falla després, la fila és WARNING amb el motiu a errors.plan.

Clients

customers_file carrega els clients de cada compte i NIF a la mateixa importació. Té una fila de capçalera amb la columna account_ref i, a les altres columnes, les de la importació de contactes d'una empresa: la capçalera de la plantilla de GET /v1/companies/{company}/contacts/import/template. Cada client va a una fila del fitxer de comptes a través del seu account_ref:

Amb el fitxer de comptes de dalt, aquest fitxer de clients envia tres clients a cliente-0042:

account_ref;name;kind;tax_id;email
cliente-0042;Bar La Plaza SL;company;B22222228;compras@barlaplaza.example
cliente-0042;Ferretería Ortiz SL;company;B33333337;info@ferreteriaortiz.example
cliente-0042;Hotel Mirador SA;company;A44444446;reservas@hotelmirador.example

Els clients passen per l'importador de contactes que ja existeix, amb el rol customer i l'estratègia de conflicte reject: un client que xoca amb un contacte existent es rebutja i l'existent es queda com està. Exportar i importar explica què accepta aquest importador. Els clients s'encuen: customers_queued compta el que s'ha encuat, i els contactes es creen després, així que la xifra no prova que ja existeixin.

Els clients d'una fila s'importen només en un NIF que la fila ha aplicat i on pots escriure. L'estat de cada fila és a customers_status, que és none (la fila no té clients), queued o blocked, i en el segon cas customers_code diu per què:

Amb una clau, accounts:write no n'hi ha prou per als clients: la clau necessita també contacts:write.

Clients sense compte: apply_customers_to_own_company

Els clients que no tenen account_ref no van enlloc, tret que enviïs apply_customers_to_own_company. Amb ella, s'importen a la teva pròpia empresa en focus: l'únic NIF de l'àmbit de la clau, o l'únic NIF del teu compte. La destinació és sempre un NIF real del teu propi compte, mai un que un altre compte t'hagi cedit. La clau necessita contacts:write, i el resultat és a own_company_customers:

own_company_customers té status (VALID, BLOCKED o ERROR), code, customers_queued i unmatched_customers, que compta els clients el account_ref dels quals no correspon a cap fila del fitxer de comptes: no s'importen enlloc, i així no es perden en silenci.

Aplicar la importació

POST /v1/accounts/imports rep el cos de la petició i l'aplica. Aplica per separat cada fila VALID, WARNING o ALREADY_EXISTS, en l'ordre del fitxer: una fila que falla surt BLOCKED o ERROR i les altres continuen. Mai no obre un checkout: cobra la teva subscripció existent, i una fila que no es pot cobrar surt BLOCKED amb el seu motiu.

curl -X POST https://api.factuarea.com/v1/accounts/imports \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "accounts_file=@accounts.csv" \
  -F "customers_file=@customers.csv" \
  -F "options[confirm_plan_changes]=false"

L'aplicació és síncrona: la resposta arriba quan acaba l'última fila, i amb un fitxer ple pot trigar uns minuts, així que deixa almenys 5 minuts al teu client. Suposa que vas treure les dues files que van sortir BLOCKED i ERROR i envies el fitxer de clients de dalt. La resposta és 201 Created:

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-8a8b8c8d8e8f",
    "object": "managed_account_import",
    "status": "completed",
    "stats": {
      "total_rows": 2,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 0,
      "error": 0,
      "created": 2,
      "reconciled": 0,
      "customers_queued": 3,
      "monthly_amount_cents": 5000,
      "proration_amount_cents": 2500
    },
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "cliente-0042",
        "tax_id": "B12345674",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": "empresario",
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750,
        "account_id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "customers_status": "queued",
        "customers_queued": 3,
        "customers_code": null,
        "claim_token": "e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3",
        "claim_url": "https://app.factuarea.com/account-claims/accept?token=e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3"
      },
      {
        "line": 3,
        "mode": "own_nif",
        "external_ref": null,
        "tax_id": "B87654323",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": null,
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null,
        "claim_token": null,
        "claim_url": null
      }
    ],
    "own_company_customers": null
  }
}

Els imports d'stats i de cada fila són els que ha cobrat l'aplicació: el prorrateig que va anunciar la previsualització, calculat de nou en aquell moment. A l'exemple, el compte gestionat de la línia 2 retorna el seu claim_token i el seu claim_url, i el NIF propi retorna null, perquè no té val.

El val de cada fila managed_account nova de producció torna una sola vegada, en aquesta resposta. Una repetició de la mateixa petició el retorna com a null, i també una fila quan send_email és true, perquè l'enllaç va per correu, i totes les files d'una importació de proves. Si en perds un, reemet-lo. La resposta no porta capçalera Location, perquè una execució no té operació pública de lectura. L'app desa l'historial i l'informe de cada importació, a Comptes de clients, Importar, Historial d'importacions, i quan una importació acaba publiquem account.import_completed als webhooks de compte del teu compte, amb l'id de l'execució i els seus stats.

Idempotency-Key i una importació alhora

L'aplicació no es pot desfer, així que exigeix una Idempotency-Key: sense ella la resposta és 422 idempotency_key_required abans de llegir res. La previsualització no la necessita. Què fa cada protecció:

Després d'un 409, espera que acabi la importació en curs i envia una altra vegada els mateixos fitxers amb una Idempotency-Key nova: les files que la primera ja va aplicar tornen ALREADY_EXISTS, mai duplicades ni cobrades dues vegades. Una importació que mai no va acabar deixa de bloquejar als 15 minuts. Un 429 no aplica res: espera el que digui Retry-After i envia la petició una altra vegada.

Amb una clau de proves

Amb una clau fact_test_ la importació treballa sobre els teus comptes de proves, i no es cobra res:

• Les files managed_account creen o concilien comptes de proves: sense cobrament, sense Stripe i sense val, així que claim_token i claim_url són null. Un compte de proves no compta per a max_managed_accounts.
• Les files own_nif surten ERROR amb code live_credential_required i sumen 0 al total: els NIF del teu propi compte només es donen d'alta en producció. El mateix val per als clients que apply_customers_to_own_company carregaria a la teva pròpia empresa.
• L'entorn és el de la clau. Una importació de proves només veu els teus comptes de proves: un external_ref que pertany a un compte de producció surt BLOCKED amb managed_account_external_ref_in_other_environment, i a l'inrevés.
• El cost és 0, a cada fila i als totals.

El flux complet amb una clau de proves és a provar comptes gestionats.

Dues coses que la importació no fa, per disseny

• Sense eina MCP. Les tres operacions són privilegiades i la importació llegeix dos fitxers pujats, que el servidor MCP no transporta. L'alternativa és l'API REST, o la importació de l'app. Des d'un agent, aprovisiona els comptes d'un en un amb l'eina provision_managed_account, que reflecteix POST /v1/accounts: mira des del servidor MCP.
• Sense sèries. El fitxer no té columna ni opció per a sèries de documents: dona d'alta comptes i NIF, no la seva numeració. Crea o canvia les sèries d'un NIF importat amb les operacions de l'eix d'empresa, per exemple POST /v1/companies/{company}/series/bootstrap, que crea en una crida les sèries per defecte que falten i necessita series:write. issuing-readiness et diu si a un NIF encara li'n falta una: no_default_series és un dels seus bloquejos, com explica què impedeix emetre a un NIF. El {company} d'un NIF importat és a companies[].id de GET /v1/accounts/{account} per a un compte gestionat, el {account} del qual és l'account_id de la fila, i a GET /v1/accounts/{account}/companies per als teus NIF propis.

Errors

Les regles que rebutjarien una provisió solta rebutgen aquí una fila, mai la petició: arriben al 201 o al 200, a l'status i el code de la fila. Aquests són els errors de la petició:

Un 429 sense un codi d'aquesta taula és un límit de la importació: una previsualització per sobre de 10 per minut, o una aplicació per sobre de 5 per minut o de 20 al dia. Espera el que digui Retry-After.

Propers passos