Zod - AbacatePay

O que é o @abacatepay/zod?

O @abacatepay/zod expõe todos os schemas públicos da API da AbacatePay usando Zod, servindo como fonte única de verdade para contratos de dados, validação runtime e geração de OpenAPI via .meta(). Não há abstrações extras nem “tipos inventados”: os schemas refletem exatamente a API documentada. Projetado para TypeScript-first, com integração direta em frameworks modernos como Elysia, Fastify, Hono, além de compatibilidade total com Node.js e Bun.

Quando usar o Zod?

Você quer contratos tipados + validação runtime
Precisa garantir compatibilidade entre versões da API
Quer gerar OpenAPI 3.1 automaticamente
Está construindo SDKs, gateways ou backends tipados

Instalação

Use o package manager da sua preferência:

bun add @abacatepay/zod
# ou
pnpm add @abacatepay/zod
# ou
npm install @abacatepay/zod

Estrutura e Versionamento

Assim como em outros pacotes da AbacatePay, os schemas são versionados por API. Importe sempre a versão correspondente à API que você está usando:

import { APICustomer } from '@abacatepay/zod/v1';
import { APISubscription } from '@abacatepay/zod/v2';

Schemas globais (ex: version, utilitários e helpers) são exportados sem versionamento:

import { version } from '@abacatepay/zod';

Por que versionar schemas?

Isso permite detectar breaking changes, manter compatibilidade e evoluir a API sem quebrar integrações existentes.

Integração com Elysia

O Zod se encaixa diretamente no Elysia, sem camadas extras.

import { Elysia } from 'elysia';
import {
    APIResponse,
    APICheckout,
    RESTPostCreateNewCheckoutBody,
} from '@abacatepay/zod/v2';

new Elysia().post(
    '/checkouts/create',
    () => {
        ...
    },
    {
        body: RESTPostCreateNewCheckoutBody,
        response: APIResponse(APICheckout),
        detail: {
            tags: ['Checkouts'],
            summary: 'Create a new checkout',
        },
    },
);

Isso garante:

Validação automática de input
Tipagem forte de output
OpenAPI gerado corretamente

Uso Básico (Validação Runtime)

Você pode validar facilmente dados retornados pela API em runtime:

import { Value } from '@sinclair/zod/value';
import { APICheckout } from '@abacatepay/zod/v2';

const data = await fetchCheckout();

if (!Value.Check(APICheckout, data)) {
    throw new Error('Invalid checkout payload');
}

Por que validar em runtime?

Tipos TypeScript não existem em produção. A validação runtime evita bugs silenciosos e payloads inválidos.

OpenAPI & JSON Schema

Todos os schemas são 100% compatíveis com OpenAPI 3.1 via JSON Schema. Isso permite:

Geração automática de documentação
Criação de SDKs tipados
Validação de breaking changes entre versões
Integração com ferramentas do ecossistema OpenAPI

Convenções de Nomenclatura

Para manter consistência e previsibilidade, os schemas seguem convenções claras: Prefixo API*

Estruturas gerais da API
Objetos retornados
Modelos públicos

Prefixo REST<HTTPMethod>*

Schemas usados em endpoints REST
- Body → corpo da requisição
- QueryParams → parâmetros de query
- Data → dados retornados

Prefixo Webhook*

Payloads de eventos de webhook

Integração com o Ecossistema

@abacatepay/rest

Cliente REST oficial que consome esses schemas.

SDKs Oficiais

SDKs de alto nível baseados nos contratos da API.

Open Source, de Verdade

Feito para desenvolvedores

O @abacatepay/zod é open source e mantido pela equipe AbacatePay. Schemas estáveis, versionados e alinhados à documentação oficial.

Documentação Completa

Veja todos os schemas, versões e exemplos de uso.

​O que é o @abacatepay/zod?

Quando usar o Zod?

​Instalação

​Estrutura e Versionamento