Documentação da API

Introdução

Bem-vindo à documentação da API da WF TECNOLOGIA!

Nossa API foi desenvolvida seguindo os padrões REST mais modernos, proporcionando uma experiência de integração simples e eficiente. Utilizamos protocolos HTTP padrão, autenticação segura e respostas em formato JSON.

Características Principais

• API RESTful com respostas em JSON
• Autenticação via Bearer Token
• Rate limiting de 1000 requisições por minuto
• Webhooks para notificações em tempo real
• SLA de 99.99% de disponibilidade
• Suporte a idempotência para operações críticas

IPs do Servidor

34.95.177.154
35.247.216.72
35.199.108.189
34.151.210.0
35.199.116.245

Primeiros Passos

Siga estas etapas para começar a integrar com a API da WF TECNOLOGIA:

1. Criar uma Conta

Se você ainda não possui uma conta, clique aqui para criar. Após a aprovação, você receberá suas credenciais de acesso.

2. Obter Credenciais

Após a aprovação da conta, você receberá:

• Client ID: Identificador único da sua aplicação
• Client Secret: Chave secreta para autenticação
• API Token: Token de acesso para as requisições

3. Configurar Whitelist de IPs

Por segurança, você deve enviar os IPs dos seus servidores para adicionarmos à lista de permissões.

4. Ambiente de Testes

Autenticação

A API da WF TECNOLOGIA utiliza autenticação Bearer Token. Todas as requisições devem incluir o token no header.

Requisição

curl --location --request POST 'https://api.wf-tecnologia.com/v1/auth/token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "client_id": "seu_client_id",
    "client_secret": "seu_client_secret",
    "grant_type": "client_credentials"
}'

Resposta

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_at": "2025-01-07T10:30:00Z"
}

Usando o Token

Inclua o token em todas as requisições subsequentes:

Authorization: Bearer seu_access_token

Pix Cash-In

O Pix Cash-In permite receber pagamentos através de QR Code ou código copia e cola. O pagador tem até 20 minutos para concluir o pagamento.

Parâmetros

Requisição

curl --location --request POST 'https://api.wf-tecnologia.com/v1/pix/cash-in' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_token' \
  --data-raw '{
    "amount": 150.00,
    "description": "Pagamento do pedido #12345",
    "payer": {
        "name": "João Silva",
        "document": "12345678900"
    },
    "expiration": 1200,
    "external_id": "pedido-12345",
    "webhook_url": "https://seu-site.com/webhook/pix"
}'

Resposta de Sucesso

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "pedido-12345",
  "status": "pending",
  "amount": 150.00,
  "description": "Pagamento do pedido #12345",
  "qr_code": "00020126580014BR.GOV.BCB.PIX...",
  "qr_code_image": "data:image/png;base64,...",
  "expires_at": "2025-01-07T10:50:00Z",
  "created_at": "2025-01-07T10:30:00Z"
}

Consultar Status

curl --location --request GET 'https://api.wf-tecnologia.com/v1/pix/cash-in/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer seu_token'

Webhook de Pagamento

Quando o pagamento for confirmado, enviaremos uma notificação para a URL configurada:

{
  "event": "pix.received",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "pedido-12345",
    "status": "completed",
    "amount": 150.00,
    "paid_at": "2025-01-07T10:35:00Z",
    "payer": {
        "name": "João Silva",
        "document": "123.456.789-00",
        "bank": "Banco do Brasil"
    },
    "end_to_end": "E18236120202501071035123456789"
  }
}

Estorno de Pix

Realize estornos totais ou parciais de pagamentos PIX recebidos.

Parâmetros

Requisição

curl --location --request POST 'https://api.wf-tecnologia.com/v1/pix/reversal' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_token' \
  --data-raw '{
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 150.00,
    "reason": "Produto devolvido",
    "external_id": "estorno-12345"
}'

Resposta

{
  "id": "660e9500-f29b-51d4-b816-556655441111",
  "external_id": "estorno-12345",
  "original_transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "amount": 150.00,
  "reason": "Produto devolvido",
  "reversal_id": "D18236120202501071045987654321",
  "created_at": "2025-01-07T10:45:00Z"
}

Pix Cash-Out

Envie pagamentos PIX instantâneos para qualquer chave PIX.

Parâmetros

Requisição

curl --location --request POST 'https://api.wf-tecnologia.com/v1/pix/cash-out' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_token' \
  --data-raw '{
    "amount": 299.90,
    "recipient": {
        "key": "12345678900",
        "key_type": "cpf"
    },
    "description": "Pagamento de comissão",
    "external_id": "pagamento-54321",
    "webhook_url": "https://seu-site.com/webhook/pix-out"
}'

Resposta

{
  "id": "770e9600-g29c-62e5-c927-667766552222",
  "external_id": "pagamento-54321",
  "status": "processing",
  "amount": 299.90,
  "recipient": {
    "key": "12345678900",
    "key_type": "cpf",
    "name": "Maria Santos",
    "bank": "Banco Itaú",
    "agency": "1234",
    "account": "56789-0"
  },
  "created_at": "2025-01-07T11:00:00Z"
}

Status do Pagamento

Os possíveis status de um pagamento PIX são:

• processing - Pagamento sendo processado
• completed - Pagamento concluído com sucesso
• failed - Pagamento falhou
• cancelled - Pagamento cancelado

Consulta de Saldo

Consulte o saldo disponível em sua conta.

Requisição

curl --location --request GET 'https://api.wf-tecnologia.com/v1/account/balance' \
  --header 'Authorization: Bearer seu_token'

Resposta

{
  "available_balance": 15750.00,
  "pending_balance": 500.00,
  "total_balance": 16250.00,
  "currency": "BRL",
  "updated_at": "2025-01-07T11:15:00Z"
}

Descrição dos Campos

• available_balance: Valor disponível para saque ou pagamentos
• pending_balance: Valor em processamento ou bloqueado
• total_balance: Soma do saldo disponível e pendente

Consulta de Transações

Liste e consulte detalhes das transações realizadas.

Parâmetros de Query

Requisição

curl --location --request GET 'https://api.wf-tecnologia.com/v1/transactions?start_date=2025-01-01&end_date=2025-01-07&type=cash_in&limit=10' \
  --header 'Authorization: Bearer seu_token'

Resposta

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "pedido-12345",
      "type": "cash_in",
      "status": "completed",
      "amount": 150.00,
      "description": "Pagamento do pedido #12345",
      "created_at": "2025-01-07T10:30:00Z",
      "completed_at": "2025-01-07T10:35:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Exportar Relatório

Webhooks

Receba notificações em tempo real sobre eventos importantes em sua conta.

Configuração

Configure URLs de webhook em cada requisição ou defina URLs padrão no painel de controle.

Eventos Disponíveis

• pix.received - Pagamento PIX recebido
• pix.sent - Pagamento PIX enviado com sucesso
• pix.failed - Falha no envio de PIX
• pix.reversed - Estorno realizado
• balance.updated - Saldo atualizado

Formato do Webhook

{
  "event": "pix.received",
  "data": {
    // Dados específicos do evento
  },
  "timestamp": "2025-01-07T10:35:00Z",
  "signature": "sha256=abc123..."
}

Validação de Assinatura

Todos os webhooks incluem uma assinatura HMAC-SHA256 no header X-Webhook-Signature para validação.

Retry Policy

Em caso de falha (status HTTP diferente de 2xx), tentaremos reenviar o webhook:

• 1ª tentativa: Imediatamente
• 2ª tentativa: Após 1 minuto
• 3ª tentativa: Após 5 minutos
• 4ª tentativa: Após 30 minutos
• 5ª tentativa: Após 2 horas

Códigos de Erro

A API retorna códigos de erro padronizados para facilitar o tratamento de exceções.

Formato de Erro

{
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo insuficiente para realizar a operação",
    "details": {
      "available_balance": 100.00,
      "required_amount": 150.00
    }
  },
  "request_id": "req_abc123"
}

Códigos Comuns

Suporte

Estamos aqui para ajudar você a integrar com sucesso nossa API.

Canais de Atendimento

Recursos Adicionais

• Postman Collection - Coleção completa de endpoints
• SDKs Oficiais - Node.js, Python, PHP e Java
• Exemplos de Código - Implementações de referência
• Status da API - Acompanhe a disponibilidade em tempo real

FAQ

Qual é o limite de transações?

Não há limite de transações. Nossa infraestrutura escala automaticamente para atender sua demanda.

Posso testar sem conta aprovada?

Sim! Use nosso ambiente sandbox com as credenciais de teste fornecidas nesta documentação.

Como aumentar meu limite de saldo?

Entre em contato com nosso suporte comercial para análise de crédito e aumento de limites.