Guia de Integração

📋 Introdução

A Order API é uma API REST desenvolvida pela Kapitale para gerenciamento de pedidos de pagamento. Esta API permite que parceiros externos integrem seus sistemas para criar, consultar, atualizar e gerenciar pedidos de forma automatizada.

Base URL

Produção: https://api.kapitale.com.br

🔐 Autenticação

Todas as rotas da API requerem autenticação via Bearer Token JWT. O token deve ser obtido através do sistema de autenticação da Kapitale (AWS Cognito).

Como obter o token

Entre em contato com a equipe da Kapitale para obter credenciais de acesso

Realize a autenticação no sistema de autenticação da Kapitale

Receba o token JWT no formato Bearer Token

Como usar o token

Inclua o token no header Authorization de todas as requisições:

Exemplo de requisição autenticada

🚀 Fluxo de Integração

Passo 1: Configuração Inicial

Antes de começar a integração, você precisará:

Credenciais de Acesso: Solicite credenciais à equipe da Kapitale

Token JWT: Obtenha um token válido através do sistema de autenticação

Ambiente: Defina se utilizará ambiente de desenvolvimento ou produção

Documentação OpenAPI: Importe o arquivo openapi-order.yaml no ApiDog ou sua ferramenta preferida

Passo 2: Buscar Informações do Varejo (GET /company/cnpj/:cnpj)

Antes de criar um pedido, é recomendado buscar as informações do varejo pelo CNPJ. Este endpoint retorna dados completos do varejo que podem ser utilizados para preencher o formulário de criação de pedido.

Endpoint: GET /company/cnpj/{cnpj}

Parâmetros:

cnpj (path): CNPJ do varejo (apenas números, 14 dígitos)

Exemplo de Requisição:

Resposta de Sucesso (200):

Cenário 1: Varejo Registrado (registered_retail: true)

{
  "name": "Empresa Varejo LTDA",
  "retail_representative": "João Silva",
  "email": "contato@varejo.com.br",
  "phone": "11987654321",
  "address": "Rua das Flores",
  "number": "123",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "complement": "Sala 45",
  "zip_code": "01310-100",
  "registered_retail": true
}

Cenário 2: Varejo Não Registrado (registered_retail: false)

{
  "name": "Nova Empresa Varejo LTDA",
  "retail_representative": "Maria Santos",
  "email": "contato@novaempresa.com.br",
  "phone": "11976543210",
  "address": "Avenida Paulista",
  "number": "1000",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "complement": "",
  "zip_code": "01310-100",
  "registered_retail": false
}

💡 Dica:

Se registered_retail for true, os dados vêm do banco de dados da Kapitale e são mais confiáveis

Se registered_retail for false, os dados foram buscados do bureau de crédito (Procob) e podem precisar de validação

Use os campos retornados (retail_representative, email, phone) para preencher o formulário de criação de pedido

Passo 3: Criar um Pedido (POST /order)

Após obter as informações do varejo, você pode criar um pedido de pagamento.

Endpoint: POST /order

Request Body:

{
  "orderNumber": "ORD-2024-001",
  "expiryDate": "2024-12-31",
  "requestedAmount": 10000.50,
  "sourceCompanyCnpj": "12345678000190",
  "destinationCompanyCnpj": "98765432000110",
  "retail_representative": "João Silva",
  "retail_email": "joao@example.com",
  "retail_phone": "11987654321"
}

Resposta de Sucesso (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_no": "ORD-2024-001",
  "expiry_date": "2024-12-31T00:00:00.000Z",
  "requested_amount": 10000.50,
  "paid_amount": 9785.49,
  "payment_status": "pending",
  "order_status": "pending",
  "retail_fee": 0,
  "industry_fee": 0.0215,
  "created_at": "2024-01-15T10:30:00.000Z"
}

⚠️ Importante:

O CNPJ deve conter apenas números (14 dígitos)

O valor solicitado deve ser maior que 1

A data de expiração deve estar no formato YYYY-MM-DD

O pedido será criado com status pending e aguardará aprovação

💡 Exemplo Prático: Usando as informações do varejo retornadas no Passo 2:

Passo 4: Consultar Pedidos

Após criar um pedido, você pode consultá-lo de várias formas:

4.1 Listar Todos os Pedidos

Endpoint: GET /order

Retorna uma lista com todos os pedidos do sistema.

4.2 Buscar Pedido por ID

Endpoint: GET /order/{id}

Exemplo:

4.3 Buscar Pedidos por CNPJ da Indústria

Endpoint: GET /order/industry/{cnpj}

Parâmetros de Query:

page (opcional): Número da página (padrão: 1)

limit (opcional): Itens por página (padrão: 10)

status (opcional): Filtro por status (ex: pending,pending_invoice)

retail_cnpj (opcional): Filtro parcial por CNPJ do varejo

Exemplo:

Resposta:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "order_no": "ORD-2024-001",
      "order_status": "pending",
      "payment_status": "pending",
      "retail": {
        "name": "Empresa Varejo LTDA",
        "cnpj": "98765432000110"
      }
    }
  ],
  "page": 1,
  "totalPages": 5,
  "limit": 10,
  "count": 50,
  "pendingInvoices": 3
}

Passo 5: Acompanhar Estatísticas

Endpoint: GET /order/statistics/{industry_cnpj}

Retorna estatísticas dos pedidos dos últimos 30 dias.

Resposta:

{
  "totalGrossValue": 150000.75,
  "totalNetValue": 50000.25,
  "pending": 30000.00
}

Passo 6: Definir Nota Fiscal (Individual)

Quando um pedido estiver com status pending_invoice, você pode anexar a nota fiscal.

Endpoint: PATCH /order/{order_id}

Request: multipart/form-data

Campos:

invoice_number (string): Número da nota fiscal

invoice (file): Arquivo PDF da nota fiscal

Exemplo usando cURL:

⚠️ Importante:

O arquivo deve ser PDF

O número da nota fiscal deve ser único

O pedido deve estar com status pending_invoice

Passo 7: Processamento em Lote (Opcional)

Para processar múltiplos pedidos de uma vez, use o endpoint de lote.

Endpoint: PATCH /order

Request: multipart/form-data

Campos:

order_list (file): Arquivo CSV com colunas numero_pedido e nota_fiscal (separados por ;)

invoices (files): Múltiplos arquivos PDF das notas fiscais

Formato do CSV:

numero_pedido;nota_fiscal
ORD-2024-001;123456
ORD-2024-002;123457

Exemplo usando cURL:

Passo 8: Cancelar Pedido (Se Necessário)

Endpoint: PATCH /order/cancel/{order_id}

Request Body:

{
  "reason": "Pedido cancelado a pedido do cliente"
}

📊 Status dos Pedidos

Order Status

Status	Descrição
`pending`	Pedido criado, aguardando processamento
`pending_invoice`	Aguardando anexo de nota fiscal
`pending_commercial_invoice`	Aguardando nota fiscal comercial
`pending_liquidation`	Aguardando liquidação
`liquidated`	Pedido liquidado
`canceled`	Pedido cancelado
`denied`	Pedido negado
`expired`	Pedido expirado

Payment Status

Status	Descrição
`pending`	Pagamento pendente
`approved`	Pagamento aprovado
`denied`	Pagamento negado
`expired`	Pagamento expirado

🔄 Fluxograma de Integração Completo

⚠️ Tratamento de Erros

A API retorna códigos HTTP padrão e mensagens de erro descritivas:

Códigos HTTP Comuns

Código	Significado	Ação Recomendada
`200`	Sucesso	Processar resposta normalmente
`201`	Criado	Pedido criado com sucesso
`400`	Requisição Inválida	Verificar dados enviados
`401`	Não Autenticado	Verificar token JWT
`404`	Não Encontrado	Verificar ID do recurso
`409`	Conflito	Recurso já existe (ex: pedido duplicado)
`500`	Erro Interno	Contatar suporte

Exemplo de Erro

{
  "statusCode": 400,
  "message": "Invalid CNPJ. Please check and try again.",
  "error": "Bad Request"
}

📝 Exemplos Práticos

Exemplo 1: Buscar Informações do Varejo e Criar Pedido (JavaScript/Node.js)

Este exemplo mostra como buscar informações do varejo e usar essas informações para criar um pedido:

Exemplo 2: Criar e Consultar Pedido (JavaScript/Node.js)

Exemplo 2: Upload de Nota Fiscal (Python)

🔍 Validações Importantes

CNPJ

Deve conter exatamente 14 dígitos numéricos

Será validado automaticamente pela API

Formato esperado: apenas números (sem pontos, barras ou hífens)

Valores Monetários

Devem ser números decimais

Valor mínimo: 1.00

Use ponto (.) como separador decimal

Datas

Formato: YYYY-MM-DD (ISO 8601)

Exemplo: 2024-12-31

Arquivos

PDFs: Apenas formato PDF para notas fiscais

CSV: Encoding UTF-8, separador ;, primeira linha como cabeçalho

📞 Suporte

Para dúvidas, problemas ou solicitações de acesso:

Email: dev@kapitale.com.br

Documentação OpenAPI: Importe o arquivo openapi-order.yaml no ApiDog

📚 Recursos Adicionais

Documentação OpenAPI: openapi-order.yaml

Ambiente de Testes: Utilize o ambiente de desenvolvimento antes de migrar para produção

Rate Limiting: Consulte limites de requisições com a equipe de suporte

Versão do Documento: 1.0.0
Última Atualização: Janeiro 2024

Guia de Integração

📋 Introdução#

Base URL#

🔐 Autenticação#

Como obter o token#

Como usar o token#

Exemplo de requisição autenticada#

🚀 Fluxo de Integração#

Passo 1: Configuração Inicial#

Passo 2: Buscar Informações do Varejo (GET /company/cnpj/:cnpj)#

Passo 3: Criar um Pedido (POST /order)#

Passo 4: Consultar Pedidos#

4.1 Listar Todos os Pedidos#

4.2 Buscar Pedido por ID#

4.3 Buscar Pedidos por CNPJ da Indústria#

Passo 5: Acompanhar Estatísticas#

Passo 6: Definir Nota Fiscal (Individual)#

Passo 7: Processamento em Lote (Opcional)#

Passo 8: Cancelar Pedido (Se Necessário)#

📊 Status dos Pedidos#

Order Status#

Payment Status#

🔄 Fluxograma de Integração Completo#

⚠️ Tratamento de Erros#

Códigos HTTP Comuns#

Exemplo de Erro#

📝 Exemplos Práticos#

Exemplo 1: Buscar Informações do Varejo e Criar Pedido (JavaScript/Node.js)#

Exemplo 2: Criar e Consultar Pedido (JavaScript/Node.js)#

Exemplo 2: Upload de Nota Fiscal (Python)#

🔍 Validações Importantes#

CNPJ#

Valores Monetários#

Datas#

Arquivos#

📞 Suporte#

📚 Recursos Adicionais#