Primeiros passos

Integre cobranças PIX no seu projeto em minutos. Todas as requisições partem do seu servidor — nunca exponha as chaves no frontend.

1. Obtenha sua chave de API

Acesse Dashboard → Projetos → [seu projeto] → API Keys em koliseu.cloud e clique em Gerar nova chave. Cada projeto pode ter até 3 chaves ativas simultâneas. A chave completa é exibida apenas uma vez — copie e guarde em segurança.

Chave de APIksl_

ksl_••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Use esta chave única em todos os endpoints. Envie no header x-api-key.

A chave ksl_ só deve ser usada no backend do seu app. Nunca coloque em código de frontend (React, mobile nativo, etc.) — qualquer pessoa que inspecionar o bundle poderia cobrar PIX em seu nome. Guarde em variáveis de ambiente do servidor, ex: KOLISEU_API_KEY.

2. Autenticação

Todos os endpoints usam a mesma chave ksl_, enviada no header x-api-key:

x-api-key: ksl_SUA_CHAVE_AQUI

Como alternativa, o header Authorization: Bearer ksl_... também é aceito. Use o que for mais conveniente para o seu SDK HTTP.

3. Exemplos rápidos

Consultar status de uma cobrança PIX

curl -X GET https://www.koliseu.cloud/api/v1/pix/payments/{id} \
  -H "x-api-key: ksl_SUA_CHAVE_AQUI"

Criar cobrança PIX

curl -X POST https://www.koliseu.cloud/api/v1/pix/payments \
  -H "x-api-key: ksl_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 9990,
    "description": "Produto X",
    "client": {
      "name": "Joao Silva",
      "email": "joao@email.com"
    }
  }'

Códigos de resposta HTTP

201Created

400Bad Request

401Unauthorized

403Forbidden

404Not Found

422Unprocessable Entity

429Rate Limit

500Internal Server Error

Estrutura de erro padrão

{
  "error": true,
  "code": "slug_do_erro",
  "message": "Descrição legível do erro",
  "status": 400
}