{ "openapi": "3.1.0", "info": { "title": "API Koku", "version": "1.0.0", "description": "API pública da Koku para cobranças Pix. Autenticação por chave de API (`Authorization: Bearer `). Valores sempre em centavos (string decimal na resposta). Mutações financeiras exigem `Idempotency-Key`. Documentação: https://docs.kokupay.com" }, "servers": [ { "url": "https://api.kokupay.com", "description": "Produção" } ], "tags": [ { "name": "Cobranças Pix" }, { "name": "Saldo e extrato" }, { "name": "Repasses" }, { "name": "Webhooks" }, { "name": "Chave de API" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Chave de API gerada no painel Koku (Desenvolvedores > Chaves de API)." } } }, "paths": { "/v1/pix/charges": { "post": { "operationId": "createCharge", "summary": "Criar cobrança Pix", "description": "Cria uma cobrança Pix e devolve o QR Code e o código copia e cola. Envie sempre os quatro dados do pagador (nome, CPF/CNPJ, e-mail e telefone): a emissão do Pix exige esses dados. Quando `status` vier `created` sem `pix`, o resultado da emissão ainda não é conhecido: consulte a cobrança depois e não crie outro pedido.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "charges:write" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "minLength": 8, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "type": "string" }, "description": "Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "CreateChargeRequest", "type": "object", "required": [ "order_reference", "amount_cents" ], "properties": { "order_reference": { "minLength": 1, "maxLength": 120, "type": "string", "description": "Identificador do pedido no seu sistema. Único por conta: não pode ser reutilizado em outra cobrança." }, "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor da cobrança em centavos, inteiro positivo (número JSON ou string decimal). `15990` = R$ 159,90." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda. Só `BRL`; pode ser omitida." }, "description": { "maxLength": 500, "type": "string", "description": "Descrição exibida para você no painel. Até 500 caracteres." }, "payer": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 200, "type": "string", "description": "Nome completo do pagador (até 200 caracteres)." }, "document": { "pattern": "^([0-9]{11}|[0-9]{14})$", "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, só números." }, "email": { "maxLength": 254, "pattern": "^[^\\s@]{1,64}@[^\\s@]{1,190}\\.[^\\s@]{2,63}$", "type": "string", "description": "E-mail do pagador. Usado só para emitir o Pix; a Koku não o grava." }, "phone": { "pattern": "^\\+?[0-9]{10,13}$", "type": "string", "description": "Telefone com DDD, só dígitos, com ou sem `+55` (ex.: `11987654321`). Usado só para emitir o Pix; a Koku não o grava." } }, "description": "Dados do pagador. Exigidos para emitir o Pix: sem eles a emissão pode ser recusada." }, "expires_in_seconds": { "minimum": 60, "maximum": 604800, "type": "integer", "description": "Validade do QR em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 3600 (1 hora)." }, "metadata": { "maxProperties": 20, "type": "object", "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Até 20 pares chave/valor de texto para o seu controle (chave até 60 e valor até 500 caracteres)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Koku." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Koku sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Koku." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Koku sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "503": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } }, "get": { "operationId": "listCharges", "summary": "Listar cobranças", "description": "Lista as cobranças da conta, das mais recentes para as mais antigas, com filtros e paginação por cursor.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "charges:read" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "description": "Filtra pelo estado da cobrança." }, { "in": "query", "name": "order_reference", "required": false, "schema": { "maxLength": 120, "type": "string" }, "description": "Filtra pelo seu identificador do pedido (valor exato)." }, { "in": "query", "name": "created_from", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Criadas a partir deste instante (inclusivo, ISO-8601)." }, { "in": "query", "name": "created_to", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Criadas antes deste instante (exclusivo, ISO-8601)." }, { "in": "query", "name": "q", "required": false, "schema": { "minLength": 1, "maxLength": 120, "type": "string" }, "description": "Busca por referência do pedido, id da cobrança, txid, E2E, nome ou documento do pagador." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Koku." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Koku sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}": { "get": { "operationId": "getCharge", "summary": "Consultar cobrança", "description": "Devolve a cobrança com o estado atual, o QR vigente e, quando paga, a tarifa e o valor líquido. Use esta consulta para confirmar um pagamento recebido por webhook.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "charges:read" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Koku." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Koku sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Koku, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}/refunds": { "post": { "operationId": "requestRefund", "summary": "Solicitar devolução", "description": "Devolve ao pagador todo ou parte do valor de uma cobrança paga. O valor é bloqueado do seu saldo na hora e a devolução é processada em seguida; acompanhe pelo caso devolvido (`status`, `execution_status`) ou pelos eventos `case.resolved` e `charge.refunded`.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "refunds:write" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança paga." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "minLength": 8, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "type": "string" }, "description": "Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "RefundRequest", "type": "object", "required": [ "amount_cents", "reason" ], "properties": { "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor a devolver em centavos. Pode ser parcial; a soma das devoluções não passa do valor pago." }, "reason": { "minLength": 3, "maxLength": 300, "type": "string", "description": "Motivo da devolução (3 a 300 caracteres)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Koku ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Koku ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}/cases": { "get": { "operationId": "listChargeCases", "summary": "Devoluções e contestações da cobrança", "description": "Lista os casos ligados a uma cobrança: devoluções pedidas por você, contestações Pix (MED) e pagamentos retidos para devolução (duplicados ou tardios).", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "charges:read", "statement:read" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Koku ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } }, "description": "Itens da página." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/balance": { "get": { "operationId": "getBalance", "summary": "Consultar saldo", "description": "Mostra a sua posição na Koku: o que está pendente de liquidação, o que já está disponível, reservas, bloqueios e quanto você tem a receber.", "tags": [ "Saldo e extrato" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "balance:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Balance", "type": "object", "required": [ "currency", "pending_cents", "available_cents", "contract_reserve_cents", "blocked_cents", "payout_reserved_cents", "total_cents", "owed_to_koku_cents", "payouts_suspended", "suspension_reasons", "payouts_by_koku", "payouts_by_koku_message", "available_for_payout_cents", "to_receive_cents", "as_of" ], "properties": { "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "pending_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Vendas pagas, ainda não liquidadas e conciliadas, em centavos." }, "available_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Vendas liquidadas e conciliadas, prontas para repasse, em centavos." }, "contract_reserve_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reserva contratual (continua sendo sua; é liberada conforme o contrato), em centavos." }, "blocked_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Bloqueado por devolução, contestação ou pagamento retido, em centavos." }, "payout_reserved_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reservado para repasses em andamento, em centavos." }, "total_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Soma das posições acima, em centavos." }, "owed_to_koku_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor devido à Koku (por exemplo, devolução maior que o saldo), em centavos." }, "payouts_suspended": { "type": "boolean", "description": "`true` quando os repasses estão suspensos (veja `suspension_reasons`)." }, "suspension_reasons": { "type": "array", "items": { "type": "string" }, "description": "Motivos da suspensão dos repasses." }, "payouts_by_koku": { "type": "boolean", "description": "`true` quando os repasses são feitos pela Koku conforme o contrato." }, "payouts_by_koku_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mensagem para exibir quando os repasses são feitos pela Koku." }, "available_for_payout_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto poderia ser sacado por pedido próprio agora. Zero quando os repasses são feitos pela Koku." }, "to_receive_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total a receber da Koku: pendente + disponível + reserva contratual (sem o bloqueado), em centavos." }, "as_of": { "format": "date-time", "type": "string", "description": "Momento da leitura do saldo." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/statement": { "get": { "operationId": "getStatement", "summary": "Consultar extrato", "description": "Lista os lançamentos que movimentaram o seu saldo. Cada venda traz bruto, tarifa e líquido; cada devolução ou contestação traz o caso e o pedido a que se refere.", "tags": [ "Saldo e extrato" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "statement:read" ], "parameters": [ { "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Início do período (inclusivo, ISO-8601). Padrão: 30 dias antes de `to`." }, { "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Fim do período (exclusivo, ISO-8601). Padrão: agora." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 500, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "as_of" ], "properties": { "items": { "type": "array", "items": { "title": "StatementEntry", "type": "object", "required": [ "journal_id", "line_no", "event_type", "description", "economic_at", "posted_at", "position", "amount_cents", "source_type", "source_id", "is_reversal", "sale", "payout", "financial_case" ], "properties": { "journal_id": { "format": "uuid", "type": "string", "description": "Identificador do lançamento contábil (vários itens podem compartilhar o mesmo)." }, "line_no": { "type": "integer", "description": "Linha dentro do lançamento." }, "event_type": { "type": "string", "description": "Fato que gerou o lançamento. Os mais comuns: `charge.paid` (venda paga), `gateway.funds_available` (venda liquidada e disponível), `gateway.external_payout` (repasse feito pela Koku para a sua conta bancária), `case.hold` e `refund.completed` (devolução). A lista completa está em Saldo e extrato." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição em texto fixo da Koku para o tipo de lançamento (ex.: `Repasse feito pela Koku (E2E...)`). Use `event_type` para decidir no código." }, "economic_at": { "format": "date-time", "type": "string", "description": "Data econômica do fato (é a data usada no filtro `from`/`to`)." }, "posted_at": { "format": "date-time", "type": "string", "description": "Momento do registro." }, "position": { "type": "string", "description": "Posição do saldo afetada: `pending`, `available`, `contract_reserve`, `case_hold`, `payout_reserved` ou `receivable`." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Efeito na posição, em centavos: positivo aumenta, negativo reduz." }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tipo do objeto de origem: `charge` (cobrança e venda), `financial_case` (caso), `gateway` (lançamento da conta como um todo, como o repasse feito pela Koku ou a compensação de valor devido; `source_id` é o id da sua conta), `gateway_receivable` ou `payout`. Use `event_type` para saber o que aconteceu." }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador do objeto de origem." }, "is_reversal": { "type": "boolean", "description": "`true` em estorno de lançamento." }, "sale": { "anyOf": [ { "type": "object", "required": [ "payment_id", "charge_id", "order_reference", "classification", "end_to_end_id", "paid_at", "gross_cents", "fee_cents", "net_cents", "reserve_cents", "payable_cents" ], "properties": { "payment_id": { "format": "uuid", "type": "string", "description": "Identificador do pagamento." }, "charge_id": { "format": "uuid", "type": "string", "description": "Cobrança da venda." }, "order_reference": { "type": "string", "description": "Seu identificador do pedido." }, "classification": { "type": "string", "description": "`primary` (venda) ou `late` (pagamento tardio)." }, "end_to_end_id": { "type": "string", "description": "Identificador fim a fim do Pix." }, "paid_at": { "format": "date-time", "type": "string", "description": "Momento do pagamento." }, "gross_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto pago, em centavos." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Tarifa da Koku, em centavos." }, "net_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Líquido da venda (bruto − tarifa), em centavos." }, "reserve_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reserva contratual retida da venda, em centavos." }, "payable_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto da venda vai para o seu saldo (líquido − reserva), em centavos." } } }, { "type": "null" } ], "description": "Venda a que o lançamento se refere (quando houver)." }, "payout": { "anyOf": [ { "type": "object", "required": [ "payout_id", "requested_cents", "fee_cents", "amount_cents" ], "properties": { "payout_id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado (pedido − taxa), em centavos." } } }, { "type": "null" } ], "description": "Saque solicitado por pedido próprio. `null` quando os repasses são feitos pela Koku." }, "financial_case": { "anyOf": [ { "type": "object", "required": [ "case_id", "case_type", "reason", "charge_id", "order_reference" ], "properties": { "case_id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "case_type": { "type": "string", "description": "Tipo do caso." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código do motivo (`duplicate_payment`, `unmatched_payment`, `late_payment_review`) ou `null`." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança do caso." }, "order_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seu identificador do pedido." } } }, { "type": "null" } ], "description": "Caso (devolução, contestação MED ou bloqueio) a que o lançamento se refere." } } }, "description": "Lançamentos do período, do mais recente para o mais antigo." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais." }, "as_of": { "format": "date-time", "type": "string", "description": "Momento da leitura." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/by-koku": { "get": { "operationId": "listPayoutsByKoku", "summary": "Listar repasses feitos pela Koku", "description": "Lista os repasses que a Koku fez para a sua conta bancária, conforme o contrato, com a referência da transferência. Cada repasse já foi descontado do saldo disponível.", "tags": [ "Repasses" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "payouts:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount_cents", "external_reference", "paid_at" ], "properties": { "id": { "type": "string", "description": "Identificador do repasse." }, "amount_cents": { "type": "string", "description": "Valor repassado, em centavos." }, "external_reference": { "type": "string", "description": "Referência da transferência (por exemplo, o identificador fim a fim do Pix)." }, "paid_at": { "type": "string", "description": "Data da transferência." } } }, "description": "Repasses feitos pela Koku, do mais recente para o mais antigo." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/event-types": { "get": { "operationId": "listEventTypes", "summary": "Listar tipos de evento", "description": "Devolve a versão do formato dos eventos, os tipos disponíveis e como a assinatura é calculada.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "event_types", "signature" ], "properties": { "version": { "type": "string", "description": "Versão do formato dos eventos." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento disponíveis." }, "signature": { "type": "object", "required": [ "header", "scheme", "extra_headers" ], "properties": { "header": { "type": "string", "description": "Cabeçalho com a assinatura." }, "scheme": { "type": "string", "description": "Formato e cálculo da assinatura." }, "extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Outros cabeçalhos enviados em cada entrega." } }, "description": "Como a assinatura é enviada." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/endpoints": { "post": { "operationId": "registerWebhookEndpoint", "summary": "Cadastrar endpoint de webhook", "description": "Cadastra a URL que vai receber os eventos. O segredo de assinatura (`signing_secret`) é devolvido uma única vez: guarde-o em local seguro.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "webhooks:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "WebhookEndpointRequest", "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 10, "maxLength": 2000, "type": "string", "description": "URL HTTPS pública que vai receber os eventos (até 2000 caracteres). Redes privadas e endereços locais são recusados." }, "event_types": { "maxItems": 30, "type": "array", "items": { "maxLength": 60, "type": "string" }, "description": "Tipos de evento a receber. Vazio ou omitido = todos." } } } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "signing_secret" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do endpoint." }, "signing_secret": { "type": "string", "description": "Segredo de assinatura. Exibido uma única vez: guarde-o em local seguro." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "Listar endpoints de webhook", "description": "Lista os endpoints cadastrados, com a situação de cada um e as falhas seguidas mais recentes.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "webhooks:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "title": "WebhookEndpoint", "type": "object", "required": [ "id", "url", "event_types", "status", "secret_last4", "created_at", "consecutive_failures", "paused_until" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do endpoint." }, "url": { "type": "string", "description": "URL cadastrada." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento assinados (vazio = todos)." }, "status": { "type": "string", "description": "Situação: `active` ou `disabled`." }, "secret_last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Últimos 4 caracteres do segredo, para conferência." }, "created_at": { "format": "date-time", "type": "string", "description": "Cadastro do endpoint." }, "consecutive_failures": { "type": "integer", "description": "Falhas técnicas seguidas nas últimas entregas (0 = saudável)." }, "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Entregas pausadas até este horário depois de falhas seguidas (`null` = sem pausa)." } } }, "description": "Itens da página." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "summary": "Desabilitar endpoint de webhook", "description": "Desabilita um endpoint: ele deixa de receber eventos. Os eventos continuam disponíveis em Listar eventos.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "webhooks:write" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador do endpoint." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Sempre `true` quando a operação foi aplicada." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/events": { "get": { "operationId": "listEvents", "summary": "Listar eventos", "description": "Lista os eventos emitidos para a sua conta, com o mesmo conteúdo enviado por webhook. A consulta não depende da entrega: use-a para conferir o que pode ter se perdido.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "webhooks:read" ], "parameters": [ { "in": "query", "name": "type", "required": false, "schema": { "maxLength": 60, "type": "string" }, "description": "Filtra pelo tipo de evento (ex.: `charge.paid`)." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "Event", "type": "object", "required": [ "id", "type", "version", "environment", "object_type", "object_id", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Identificador do evento (`evt_...`). É o mesmo em todas as tentativas de entrega: use-o para não processar duas vezes." }, "type": { "type": "string", "description": "Tipo do evento (ex.: `charge.paid`)." }, "version": { "type": "string", "description": "Versão do formato do evento (`v1`)." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "object_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tipo do objeto do evento (ex.: `charge`)." }, "object_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador do objeto." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do fato." }, "data": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Dados do evento. O formato de cada tipo está em Eventos e payloads." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Listar entregas", "description": "Mostra o resultado técnico de cada tentativa de entrega aos seus endpoints. Uma falha de entrega nunca altera cobrança, saldo ou extrato.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-koku-scopes": [ "webhooks:read" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "delivered" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "dead_letter" ] } ] }, "description": "Filtra pelo resultado técnico da entrega." }, { "in": "query", "name": "endpoint_id", "required": false, "schema": { "format": "uuid", "type": "string" }, "description": "Filtra por endpoint." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "WebhookDelivery", "type": "object", "required": [ "id", "endpoint_id", "endpoint_url", "event_id", "event_type", "status", "attempts", "last_response_status", "last_response_ms", "last_error", "last_attempt_at", "next_attempt_at", "delivered_at", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da entrega." }, "endpoint_id": { "format": "uuid", "type": "string", "description": "Endpoint de destino." }, "endpoint_url": { "type": "string", "description": "URL do endpoint." }, "event_id": { "type": "string", "description": "Evento entregue." }, "event_type": { "type": "string", "description": "Tipo do evento." }, "status": { "type": "string", "description": "Resultado técnico: `pending`, `delivered`, `failed` ou `dead_letter` (tentativas esgotadas)." }, "attempts": { "type": "integer", "description": "Tentativas feitas." }, "last_response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Status HTTP da última resposta do seu endpoint." }, "last_response_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Tempo da última resposta, em milissegundos." }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Último erro técnico (ex.: tempo esgotado)." }, "last_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Última tentativa." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Próxima tentativa agendada." }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Entrega confirmada (resposta 2xx)." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da entrega." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/api-keys/current": { "get": { "operationId": "currentApiKey", "summary": "Dados da chave atual", "description": "Devolve os dados da chave usada na requisição (nunca o segredo). Útil para conferir ambiente e escopos na subida da integração.", "tags": [ "Chave de API" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "prefix", "gateway_id", "environment", "scopes", "expires_at", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da chave." }, "name": { "type": "string", "description": "Nome dado à chave no painel." }, "prefix": { "type": "string", "description": "Prefixo público da chave (o segredo nunca é devolvido)." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Koku." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da chave: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Escopos concedidos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Expiração da chave (`null` = sem expiração)." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da chave." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Koku ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } } } }