API legada/Referência completa/Integração ERP (1.0)

Códigos de pagamento

Lê e grava, por CNPJ, quais meios de pagamento cada cliente B2B pode usar no checkout, a partir dos códigos do ERP.

Em vendas B2B (empresa para empresa), nem todo cliente pode pagar de qualquer jeito: um cliente novo paga à vista, um cliente com crédito aprovado pode usar boleto faturado em 30 dias. É o ERP que sabe disso. Estas rotas deixam o ERP liberar ou bloquear meios de pagamento por cliente, identificando cada meio pelo código que a loja cadastrou nele (o "código de pagamento").

A regra que o checkout aplica ao cliente depende do que foi gravado:

O que está gravado para o cliente	O que o checkout oferece
Nada	Todos os meios da loja.
Algum meio com situação `A` (ativo)	Só os meios marcados `A` (lista de permitidos).
Só meios com situação `D` (desativado)	Todos, menos os marcados `D` (lista de bloqueados).

GET/api/v1.0/payment_codesAdmin

Ler os códigos de pagamento de um cliente (API 1.0)

Devolve o que está gravado para o cliente, um item por meio de pagamento. Informe user_id ou cnpj; se vierem os dois, vale o user_id.

Parâmetros de consulta

user_iduuid

Id do cliente.

cnpjstring

CNPJ do cliente, com ou sem pontuação. Se mais de um cliente tem o mesmo CNPJ, todos entram na resposta.

POST/api/v1.0/payment_codesAdmin

Gravar os códigos de pagamento de clientes (API 1.0)

Grava, para cada CNPJ da lista, quais meios ficam liberados ou bloqueados. Se um CNPJ pertence a mais de um usuário da loja, todos recebem a mesma regra. Responde 201, mesmo quando alguns itens são ignorados: confira skipped e codes_skipped.

Corpo da requisição

company_idintegerobrigatório

Número da empresa (seller) na 1.0. Precisa ser diferente de zero, mas o valor não altera o resultado: a regra vale para o cliente na loja inteira.

paymentsarrayobrigatório

Lista de clientes, no mínimo um.

payments[].cnpjstringobrigatório

CNPJ do cliente. Vazio é ignorado (empty_cnpj).

payments[].codesarray

Meios de pagamento do cliente.

payments[].codes[].codestringobrigatório

Código do meio de pagamento. A plataforma procura primeiro o campo de código de pagamento, depois o slug e por fim o provedor, sem diferenciar maiúsculas.

payments[].codes[].statusstringobrigatório

AD

A libera, D bloqueia. Também aceitos: active, enabled, 1, true, y, yes, on (liberam) e disabled, inactive, 0, false, n, no, off, h (bloqueiam). Outro valor ignora o código (invalid_status).

modestringpadrão: replace

replacemerge

replace apaga tudo o que havia do cliente e grava só esta lista. merge acrescenta ou atualiza os códigos enviados e mantém os demais.

GET/api/payment_codesAdmin

Mesma leitura, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/payment_codes. Os ids de usuário e de meio de pagamento saem como decimais.

POST/api/payment_codesAdmin

Mesma gravação, sem o prefixo /v1.0

Idêntica a POST /api/v1.0/payment_codes.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/payment_codes" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": 1,
  "mode": "replace",
  "payments": [
    {
      "cnpj": "11.222.333/0001-81",
      "codes": [
        {
          "code": "BOLETO30",
          "status": "A"
        },
        {
          "code": "PIX",
          "status": "A"
        }
      ]
    }
  ]
}'

Ler o que ficou gravado:

bash

curl "$BASE_URL/api/v1.0/payment_codes?cnpj=11222333000181" \
  -u "$EMAIL:$API_KEY"

Resposta

201Gravação concluída

json

{
  "count": 1,
  "processed": 1,
  "message": "payment codes assignment completed",
  "results": [
    {
      "cnpj": "11.222.333/0001-81",
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "assigned": 2,
      "codes_skipped": []
    }
  ],
  "skipped": null
}

200Leitura

json

{
  "payments": [
    {
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "code": "BOLETO30",
      "payment_code": "BOLETO30",
      "payment_method_id": "5c1f2a77-1b0e-4a59-9a1e-0f0a3a2f7d11",
      "method_name": "Boleto 30 dias",
      "status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

countinteger

Quantos usuários foram gravados. Repete processed.

processedinteger

Quantos usuários foram gravados. Um CNPJ com três usuários conta três.

results[]array

Um item por usuário gravado: cnpj, user_id, assigned (quantos códigos foram gravados) e codes_skipped.

results[].codes_skippedarray

Códigos ignorados, no formato codigo:motivo. Motivos: not_found (nenhum meio com esse código) e invalid_status.

skippedarray | null

CNPJs ignorados, com cnpj e reason: empty_cnpj, user_not_found (nenhum usuário com esse CNPJ) ou o texto do erro ao gravar. null quando não há.

payments[].user_iduuid

Cliente (na leitura).

payments[].codestring

Código do meio: o código de pagamento, ou o slug se não houver código.

payments[].payment_codestring

Código de pagamento cadastrado no meio. Ausente se não houver.

payments[].payment_method_iduuid

Id do meio de pagamento.

payments[].method_namestring

Nome do meio.

payments[].statusstring

AD

A liberado, D bloqueado.

totalinteger

Quantidade de itens em payments.

Erros

Status	Quando	Corpo
400	Leitura sem `user_id` nem `cnpj`	`{"message":"cnpj or user_id is required","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	`company_id` ausente ou zero	`{"message":"company_id is required","status":400}`
400	`payments` vazio	`{"message":"payments is required","status":400}`
401	Sem credencial	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Credencial que não é de administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Falha ao ler	`{"message":"failed to list payment codes","status":500}`

Veja também

Códigos de pagamento

Lê e grava, por CNPJ, quais meios de pagamento cada cliente B2B pode usar no checkout, a partir dos códigos do ERP.

A regra que o checkout aplica ao cliente depende do que foi gravado:

O que está gravado para o cliente	O que o checkout oferece
Nada	Todos os meios da loja.
Algum meio com situação `A` (ativo)	Só os meios marcados `A` (lista de permitidos).
Só meios com situação `D` (desativado)	Todos, menos os marcados `D` (lista de bloqueados).

GET/api/v1.0/payment_codesAdmin

Ler os códigos de pagamento de um cliente (API 1.0)

Devolve o que está gravado para o cliente, um item por meio de pagamento. Informe user_id ou cnpj; se vierem os dois, vale o user_id.

Parâmetros de consulta

user_iduuid

Id do cliente.

cnpjstring

CNPJ do cliente, com ou sem pontuação. Se mais de um cliente tem o mesmo CNPJ, todos entram na resposta.

POST/api/v1.0/payment_codesAdmin

Gravar os códigos de pagamento de clientes (API 1.0)

Corpo da requisição

company_idintegerobrigatório

Número da empresa (seller) na 1.0. Precisa ser diferente de zero, mas o valor não altera o resultado: a regra vale para o cliente na loja inteira.

paymentsarrayobrigatório

Lista de clientes, no mínimo um.

payments[].cnpjstringobrigatório

CNPJ do cliente. Vazio é ignorado (empty_cnpj).

payments[].codesarray

Meios de pagamento do cliente.

payments[].codes[].codestringobrigatório

Código do meio de pagamento. A plataforma procura primeiro o campo de código de pagamento, depois o slug e por fim o provedor, sem diferenciar maiúsculas.

payments[].codes[].statusstringobrigatório

AD

modestringpadrão: replace

replacemerge

replace apaga tudo o que havia do cliente e grava só esta lista. merge acrescenta ou atualiza os códigos enviados e mantém os demais.

GET/api/payment_codesAdmin

Mesma leitura, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/payment_codes. Os ids de usuário e de meio de pagamento saem como decimais.

POST/api/payment_codesAdmin

Mesma gravação, sem o prefixo /v1.0

Idêntica a POST /api/v1.0/payment_codes.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/payment_codes" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": 1,
  "mode": "replace",
  "payments": [
    {
      "cnpj": "11.222.333/0001-81",
      "codes": [
        {
          "code": "BOLETO30",
          "status": "A"
        },
        {
          "code": "PIX",
          "status": "A"
        }
      ]
    }
  ]
}'

Ler o que ficou gravado:

bash

curl "$BASE_URL/api/v1.0/payment_codes?cnpj=11222333000181" \
  -u "$EMAIL:$API_KEY"

Resposta

201Gravação concluída

json

{
  "count": 1,
  "processed": 1,
  "message": "payment codes assignment completed",
  "results": [
    {
      "cnpj": "11.222.333/0001-81",
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "assigned": 2,
      "codes_skipped": []
    }
  ],
  "skipped": null
}

200Leitura

json

{
  "payments": [
    {
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "code": "BOLETO30",
      "payment_code": "BOLETO30",
      "payment_method_id": "5c1f2a77-1b0e-4a59-9a1e-0f0a3a2f7d11",
      "method_name": "Boleto 30 dias",
      "status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

countinteger

Quantos usuários foram gravados. Repete processed.

processedinteger

Quantos usuários foram gravados. Um CNPJ com três usuários conta três.

results[]array

Um item por usuário gravado: cnpj, user_id, assigned (quantos códigos foram gravados) e codes_skipped.

results[].codes_skippedarray

Códigos ignorados, no formato codigo:motivo. Motivos: not_found (nenhum meio com esse código) e invalid_status.

skippedarray | null

CNPJs ignorados, com cnpj e reason: empty_cnpj, user_not_found (nenhum usuário com esse CNPJ) ou o texto do erro ao gravar. null quando não há.

payments[].user_iduuid

Cliente (na leitura).

payments[].codestring

Código do meio: o código de pagamento, ou o slug se não houver código.

payments[].payment_codestring

Código de pagamento cadastrado no meio. Ausente se não houver.

payments[].payment_method_iduuid

Id do meio de pagamento.

payments[].method_namestring

Nome do meio.

payments[].statusstring

AD

A liberado, D bloqueado.

totalinteger

Quantidade de itens em payments.

Erros

Status	Quando	Corpo
400	Leitura sem `user_id` nem `cnpj`	`{"message":"cnpj or user_id is required","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	`company_id` ausente ou zero	`{"message":"company_id is required","status":400}`
400	`payments` vazio	`{"message":"payments is required","status":400}`
401	Sem credencial	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Credencial que não é de administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Falha ao ler	`{"message":"failed to list payment codes","status":500}`