API legada/Referência completa/Parceiros, clientes B2B e representantes

Carga de clientes por CNPJ

Atualiza em lote situação, grupos de usuários e formas de pagamento de clientes identificados pelo CNPJ.

Esta é a rota que um ERP usa para dizer à loja "este cliente foi aprovado, está no grupo Atacado e só pode pagar com boleto e PIX". Cada item do corpo identifica o cliente pelo CNPJ, e a plataforma localiza todos os usuários com esse CNPJ e aplica as mudanças.

O corpo pode ser um objeto ou um vetor de objetos. Por item, nesta ordem: (1) muda a situação do usuário, (2) coloca-o nos grupos informados, (3) substitui a lista de formas de pagamento permitidas. Cada parte só roda se o item a traz.

Itens que não puderam ser aplicados (usuário não encontrado, grupo ou forma de pagamento desconhecidos, situação inválida) não derrubam a chamada: aparecem em skipped, e o status HTTP vira 207 em vez de 200.

POST/api/v1.0/customerAdmin

Atualizar clientes em lote pelo CNPJ

Corpo da requisição

CNPJstringobrigatório

CNPJ do cliente, com ou sem pontuação. A chave é escrita em maiúsculas. Itens sem CNPJ são ignorados em silêncio (não entram em skipped).

statusstring

ADPactivedisabledpending

Nova situação do usuário. Se vier, todo usuário com esse CNPJ muda e perde as sessões abertas (precisa entrar de novo).

usergroupsarray

Grupos a atribuir. Cada item é um objeto com os campos abaixo.

usergroups[].codestring

Nome do grupo (sem diferenciar maiúsculas) ou o id do grupo. Item com code vazio é ignorado.

usergroups[].statusstringpadrão: A

Situação do vínculo. Vazio vale A.

paymentsarray

Formas de pagamento permitidas ao cliente. Substitui a lista inteira; mande todas as que devem valer. Cada item é um objeto com os campos abaixo.

payments[].codestring

Código da forma de pagamento: o código cadastrado, o slug ou o provedor, sem diferenciar maiúsculas.

payments[].statusstringpadrão: A

A (permitida) ou D (bloqueada). Aceita também active/disabled, 1/0, Y/N. Vazio ou texto não reconhecido vale A (permitida), então confira a grafia.

POST/api/customerAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/customer. Use este caminho se o seu cliente já foi escrito para ele.

Exemplo de requisição

bash

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

Resposta

200Tudo aplicado

json

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

207Aplicado em parte

json

{
  "processed": 0,
  "total": 2,
  "payments_applied": 0,
  "skipped": [{ "cnpj": "00000000000191", "reason": "user_not_found" }]
}

Campos da resposta

processedinteger

Itens com CNPJ para os quais ao menos um usuário foi encontrado e processado.

totalinteger

Itens recebidos no corpo (inclusive os sem CNPJ).

payments_appliedinteger

Quantidade de usuários cuja lista de formas de pagamento foi substituída.

skippedarray

Itens ou partes não aplicados, ou null quando nada foi pulado. Cada elemento tem cnpj e reason (user_not_found, usergroup_code_not_found, payment_code_not_found, status_update_failed: ..., status_read_after_write_failed: ..., usergroups_lookup_failed: ..., usergroup_update_failed: ..., ou a mensagem de erro de uma falha ao gravar os pagamentos), mais code ou user_id quando aplicável.

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`
400	Corpo que não é JSON, ou que não é objeto nem vetor de objetos.	`{"status":400,"message":"invalid request body"}`
207	Sucesso parcial: veja `skipped`.	`{"payments_applied":0,"processed":0,"skipped":[{"cnpj":"00000000000191","reason":"user_not_found"}],"total":2}`

Veja também

Carga de clientes por CNPJ

Atualiza em lote situação, grupos de usuários e formas de pagamento de clientes identificados pelo CNPJ.

POST/api/v1.0/customerAdmin

Atualizar clientes em lote pelo CNPJ

Corpo da requisição

CNPJstringobrigatório

CNPJ do cliente, com ou sem pontuação. A chave é escrita em maiúsculas. Itens sem CNPJ são ignorados em silêncio (não entram em skipped).

statusstring

ADPactivedisabledpending

Nova situação do usuário. Se vier, todo usuário com esse CNPJ muda e perde as sessões abertas (precisa entrar de novo).

usergroupsarray

Grupos a atribuir. Cada item é um objeto com os campos abaixo.

usergroups[].codestring

Nome do grupo (sem diferenciar maiúsculas) ou o id do grupo. Item com code vazio é ignorado.

usergroups[].statusstringpadrão: A

Situação do vínculo. Vazio vale A.

paymentsarray

Formas de pagamento permitidas ao cliente. Substitui a lista inteira; mande todas as que devem valer. Cada item é um objeto com os campos abaixo.

payments[].codestring

Código da forma de pagamento: o código cadastrado, o slug ou o provedor, sem diferenciar maiúsculas.

payments[].statusstringpadrão: A

A (permitida) ou D (bloqueada). Aceita também active/disabled, 1/0, Y/N. Vazio ou texto não reconhecido vale A (permitida), então confira a grafia.

POST/api/customerAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/customer. Use este caminho se o seu cliente já foi escrito para ele.

Exemplo de requisição

bash

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

Resposta

200Tudo aplicado

json

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

207Aplicado em parte

json

{
  "processed": 0,
  "total": 2,
  "payments_applied": 0,
  "skipped": [{ "cnpj": "00000000000191", "reason": "user_not_found" }]
}

Campos da resposta

processedinteger

Itens com CNPJ para os quais ao menos um usuário foi encontrado e processado.

totalinteger

Itens recebidos no corpo (inclusive os sem CNPJ).

payments_appliedinteger

Quantidade de usuários cuja lista de formas de pagamento foi substituída.

skippedarray

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`
400	Corpo que não é JSON, ou que não é objeto nem vetor de objetos.	`{"status":400,"message":"invalid request body"}`
207	Sucesso parcial: veja `skipped`.	`{"payments_applied":0,"processed":0,"skipped":[{"cnpj":"00000000000191","reason":"user_not_found"}],"total":2}`