Get in Touch

Have a question about the platform, need help with your integration, or want to discuss partnership opportunities and enterprise pricing? Drop us an email — we’ll do our best to get back to you within 3–4 hours.

contact@fiwano.com
Menu da documentação

Documentação da API Fiwano

Feito para pessoas e agentes de IA

Cada página aqui é legível por humanos — guias por tarefa e conceitos — apoiada por um contrato OpenAPI completo. A mesma referência vem em um cookbook aberto que você clona no seu projeto em segundos.

Trabalhando com um agente de IA? Clone o cookbook

Recomendado

Aponte seu agente para o PLAYBOOK.md — um guia passo a passo para a referência da API e exemplos prontos, para ele ler só o necessário em cada etapa.

Ver o cookbook no GitHub

Prefere colar como contexto? Baixe a documentação completa em um único arquivo Markdown, ou pegue só a spec.

Baixar .md Spec bruta: openapi.json · openapi.yaml

Autenticação

Todas as requisições à API exigem uma chave de API no header X-API-Key.

Crie uma chave na página API Keys do portal. A chave completa é exibida apenas uma vez — guarde-a com segurança. Chaves perdidas não podem ser recuperadas; revogue e crie uma nova.

curl https://fiwano.com/api/v1/channels \
  -H "X-API-Key: YOUR_API_KEY"

Todas as chaves começam com mip_live_. As chaves são armazenadas como hash do nosso lado.

Erros

Toda resposta de erro tem um campo detail. A maioria dos erros de domínio usa uma descrição legível:

{ "detail": "Human-readable error description" }

A validação de esquema (422) usa uma lista de erros de campo. Alguns erros de validação de domínio usam um objeto detail estruturado com um campo code — por exemplo text_too_long ao enviar um texto longo demais, invalid_recipient (400) quando recipient está vazio, não contém dígitos ou não é um PSID/IGSID numérico em um canal do Messenger/Instagram (reason indica qual; hint diz o que enviar no lugar), ou recipient_equals_sender (400) quando um envio de WhatsApp é endereçado ao próprio número do canal. Os formatos por endpoint estão na Referência da API.

Códigos de status HTTP

Código Significado O que fazer
200 Sucesso —
201 Criado —
400 Requisição inválida Verifique o campo detail
401 Não autorizado Verifique seu header X-API-Key
402 Pagamento necessário Período de teste encerrado ou assinatura inativa — veja Assinaturas e Cobrança
404 Não encontrado O recurso não existe ou pertence a outra conta
422 Erro de validação Verifique campos obrigatórios, tipos e restrições de campo em detail
429 Limite de taxa excedido Reduza o ritmo e tente novamente após Retry-After — veja limites de taxa
502 Erro da API da Meta Falha no upstream. Verifique detail. Tentar novamente pode ajudar.
503 Sobrecarregado temporariamente Descarte de carga transitório. Tente novamente após Retry-After.

Códigos de erro de envio

Os três endpoints de envio respondem 200 mesmo quando o envio falha — o resultado está em success, status e error_code. Veja Entrega e novas tentativas.

error_code é o código de erro da Meta, repassado sem alteração. Ele só está presente quando a falha veio da Meta; uma rejeição pelo próprio Fiwano usa um código de status HTTP da tabela acima. error sempre traz uma descrição legível e, em envios de mídia, uma dica sobre a causa provável.

error_code Significado Nova tentativa pelo Fiwano O que fazer
10, 200 A Meta nega esta ação para a conta não Não é problema de token: o canal continua conectado e recebendo. Leia error (texto da própria Meta) e verifique a conta nas Configurações do Negócio da Meta
10 com another app is controlling this thread Instagram/Messenger: outro app conectado controla a conversa não Defina o Fiwano como app de roteamento padrão ou desconecte o outro app — veja Pré-requisitos
100 Parâmetro inválido — a Meta reutiliza este código para causas distintas, incluindo arquivo acima do limite de tamanho não Leia error para a causa específica; verifique media_url, media_type, formato do destinatário e o tamanho do arquivo
190 Token de acesso expirado ou revogado não Reconecte o canal
368 Conta temporariamente bloqueada por violação de políticas não Resolva no Meta Business Manager
551 Messenger/Instagram: esta pessoa não pode receber mensagens agora — bloqueou a Página, encerrou a conversa, restringiu mensagens de empresas ou nunca escreveu para a Página não Nada a fazer do seu lado; só a pessoa pode reverter. Não reenvie automaticamente
803 Objeto não existe ou está indisponível não Verifique o identificador do destinatário
131008 Parâmetro obrigatório ausente não Corrija o payload
131009 Valor de parâmetro inválido para este canal não Corrija o payload
131026 Destinatário não acessível nesta plataforma não Verifique o destinatário
131047 Janela de reengajamento de 24h fechada não Envie um modelo aprovado do WhatsApp — veja janelas de mensagens
131051 Tipo de mensagem não suportado neste canal não Verifique as capacidades do canal
131052 A Meta não conseguiu baixar a media_url não Verifique se a URL retorna 200, se o Content-Type corresponde ao media_type e se a assinatura não expirou
131053 A Meta não conseguiu processar a mídia sim Geralmente transitório; verifique formato e tamanho se persistir
131056 Limite de taxa entre este remetente e destinatário sim Reduza o ritmo de mensagens para esse destinatário
131057 Conta do WhatsApp Business em modo de manutenção (por exemplo, upgrade de throughput) sim Geralmente temporário; nenhuma ação

Códigos fora desta tabela são repassados como a Meta os retorna. Tudo que não for reconhecido como permanente é tratado como transitório e repetido.

Respostas lentas da Meta

Ocasionalmente a Meta leva mais de 30 segundos — às vezes mais de um minuto — para responder a um envio, na maioria das vezes enquanto baixa um arquivo de mídia grande. O Fiwano não marca a mensagem como falha: a chamada retorna success: true, status: "queued", e o message_id é definitivo. O Fiwano então conclui o envio junto à Meta por você. O que você vê:

  • Os webhooks habituais message.sent / message.delivered / message.read para esse message_id, exatamente como para uma mensagem que retornou sent de imediato.
  • Em casos raros a mensagem chega ao destinatário duas vezes: se a Meta não confirmar o envio em alguns minutos, o Fiwano o envia mais uma vez, e a primeira tentativa pode ter sido concluída afinal. Uma duplicata é preferível a uma mensagem perdida.
  • Se a mensagem não puder ser confirmada de forma alguma, ela passa a failed e o dono do canal recebe o e-mail de resumo de entrega.

Não reenvie do seu lado enquanto a mensagem estiver queued. O mesmo vale se o seu próprio cliente HTTP atingir o timeout — veja Tempo de resposta.

Compatibilidade

A Fiwano não tem números de versão. O contrato da API é o v1 (https://fiwano.com/api/v1), estável desde o lançamento público em março de 2026. O serviço é atualizado continuamente; os novos recursos aparecem no changelog (com feed Atom).

Toda mudança no v1 é aditiva:

  • novos endpoints;
  • novos parâmetros e campos opcionais de requisição;
  • novos campos em respostas e payloads de webhook;
  • novos tipos de evento de webhook e novos valores em conjuntos abertos, como status de entrega ou dicas de erro.

O que não muda: endpoints existentes, nomes, tipos e significados dos campos; a autenticação por X-API-Key; o esquema de assinatura dos webhooks. Novos tipos de evento de webhook nunca são ativados nos seus canais sem uma ação sua — você faz opt-in por canal via webhook_events.

O que sua integração precisa fazer para continuar compatível: ignorar campos que não conhece e ignorar tipos de evento que não ativou. Não trate um campo desconhecido ou um novo valor em um conjunto aberto como erro.

Se uma mudança incompatível um dia for inevitável, ela sairá como uma nova versão da API ao lado do v1, anunciada no changelog e por e-mail com antecedência. O v1 continua funcionando.