Sincronização por CNPJ

Atualize em lote status, grupos e formas de pagamento de clientes identificados pelo CNPJ, a chamada que um ERP usa para refletir a carteira comercial.

Muitas empresas mantêm no ERP a regra comercial de cada cliente: se está liberado ou bloqueado, a qual tabela de preços (grupo) pertence e quais formas de pagamento pode usar. Esta rota recebe essa foto do ERP, identificando cada cliente pelo CNPJ, e a aplica de uma vez: status da conta, grupos de usuários e regras de pagamento.

A rota é POST /api/v1.0/customers, que também responde em /api/customers (os apelidos no singular /customer também funcionam). Não cria clientes: o cliente já precisa existir com aquele CNPJ (Criar cliente).

POST/api/v1.0/customersAdmin

Atualizar clientes em lote por CNPJ

O corpo pode ser um objeto ou uma lista de objetos, um por cliente. Cada chave é opcional, exceto CNPJ. Itens sem CNPJ são ignorados em silêncio.

Corpo da requisição (cada cliente)

CNPJstringobrigatório

CNPJ do cliente, com ou sem máscara. Procura as contas que têm esse documento.

statusstring

ADP

Muda o status de todas as contas do CNPJ (letra ou palavra active, disabled, pending). Também encerra as sessões delas.

usergroupsarray

Grupos a vincular. Um grupo que não existe é pulado e registrado em skipped.

codestringobrigatório

Nome do grupo (sem diferenciar maiúsculas) ou o id do grupo.

statusstringpadrão: A

APFD

Status do vínculo. F desfaz o vínculo (veja Vínculo com grupos). Padrão: A.

paymentsarray

Formas de pagamento permitidas (A) ou bloqueadas (D). Substitui a regra existente das contas.

codestringobrigatório

Código da forma de pagamento (pix, boleto, credit_card).

statusstringpadrão: A

AD

A libera, D bloqueia.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/customers" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "CNPJ": "11.222.333/0001-81",
      "status": "A",
      "usergroups": [{"code": "Atacado", "status": "A"}],
      "payments": [{"code": "pix", "status": "A"}, {"code": "boleto", "status": "A"}]
    },
    {"CNPJ": "45.723.174/0001-10", "status": "D"}
  ]'

Resposta

200Tudo aplicado

json

{ "processed": 2, "total": 2, "payments_applied": 1, "skipped": null }

207Aplicado com pendências

json

{
  "processed": 1,
  "total": 2,
  "payments_applied": 1,
  "skipped": [
    { "cnpj": "11.222.333/0001-81", "code": "Inexistente", "reason": "usergroup_code_not_found" },
    { "cnpj": "45.723.174/0001-10", "reason": "user_not_found" }
  ]
}

Campos da resposta

processedinteger

Quantos itens da lista tiveram ao menos uma conta encontrada. Um item com grupo desconhecido ainda conta como processado (o resto dele foi aplicado).

totalinteger

Quantos itens foram enviados.

payments_appliedinteger

Quantas contas tiveram a regra de pagamento gravada (não é a quantidade de formas).

skippedarray

O que não pôde ser aplicado, com cnpj, o motivo em reason e, quando cabe, user_id ou code. null se nada foi pulado.

skipped[].reasonstring

user_not_found (nenhuma conta com o CNPJ), usergroup_code_not_found, payment_code_not_found, status_update_failed: ..., usergroup_update_failed: ....

Erros

Status	Quando	Corpo
207	Parte do pedido não foi aplicada	Corpo acima, com `skipped` preenchido. Não é erro de rede: leia `skipped`.
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também

Sincronização por CNPJ

Atualize em lote status, grupos e formas de pagamento de clientes identificados pelo CNPJ, a chamada que um ERP usa para refletir a carteira comercial.

POST/api/v1.0/customersAdmin

Atualizar clientes em lote por CNPJ

O corpo pode ser um objeto ou uma lista de objetos, um por cliente. Cada chave é opcional, exceto CNPJ. Itens sem CNPJ são ignorados em silêncio.

Corpo da requisição (cada cliente)

CNPJstringobrigatório

CNPJ do cliente, com ou sem máscara. Procura as contas que têm esse documento.

statusstring

ADP

Muda o status de todas as contas do CNPJ (letra ou palavra active, disabled, pending). Também encerra as sessões delas.

usergroupsarray

Grupos a vincular. Um grupo que não existe é pulado e registrado em skipped.

codestringobrigatório

Nome do grupo (sem diferenciar maiúsculas) ou o id do grupo.

statusstringpadrão: A

APFD

Status do vínculo. F desfaz o vínculo (veja Vínculo com grupos). Padrão: A.

paymentsarray

Formas de pagamento permitidas (A) ou bloqueadas (D). Substitui a regra existente das contas.

codestringobrigatório

Código da forma de pagamento (pix, boleto, credit_card).

statusstringpadrão: A

AD

A libera, D bloqueia.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/customers" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "CNPJ": "11.222.333/0001-81",
      "status": "A",
      "usergroups": [{"code": "Atacado", "status": "A"}],
      "payments": [{"code": "pix", "status": "A"}, {"code": "boleto", "status": "A"}]
    },
    {"CNPJ": "45.723.174/0001-10", "status": "D"}
  ]'

Resposta

200Tudo aplicado

json

{ "processed": 2, "total": 2, "payments_applied": 1, "skipped": null }

207Aplicado com pendências

json

{
  "processed": 1,
  "total": 2,
  "payments_applied": 1,
  "skipped": [
    { "cnpj": "11.222.333/0001-81", "code": "Inexistente", "reason": "usergroup_code_not_found" },
    { "cnpj": "45.723.174/0001-10", "reason": "user_not_found" }
  ]
}

Campos da resposta

processedinteger

Quantos itens da lista tiveram ao menos uma conta encontrada. Um item com grupo desconhecido ainda conta como processado (o resto dele foi aplicado).

totalinteger

Quantos itens foram enviados.

payments_appliedinteger

Quantas contas tiveram a regra de pagamento gravada (não é a quantidade de formas).

skippedarray

O que não pôde ser aplicado, com cnpj, o motivo em reason e, quando cabe, user_id ou code. null se nada foi pulado.

skipped[].reasonstring

user_not_found (nenhuma conta com o CNPJ), usergroup_code_not_found, payment_code_not_found, status_update_failed: ..., usergroup_update_failed: ....

Erros

Status	Quando	Corpo
207	Parte do pedido não foi aplicada	Corpo acima, com `skipped` preenchido. Não é erro de rede: leia `skipped`.
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`