Wortic

Documentação da API de CEP

Um endereço, uma resposta em JSON. Copie o exemplo da sua linguagem e rode: não precisa de cadastro nem de chave.

Publicado em . Fontes oficiais: o CEP nos Correios e os códigos de município do IBGE.

Comece em um minuto

O exemplo busca o endereço pelo CEP e mostra a rua, a cidade e o código IBGE. Troque o número pelo CEP que você quer.

curl https://cep.wortic.com/cep/01001000

Saída esperada: Praça da Sé - São Paulo/SP - IBGE 3550308. Java e Kotlin mostram o código HTTP e o JSON inteiro.

No seu framework

A mesma consulta, escrita do jeito de cada pilha. TypeScript, Dart, Objective-C e COBOL rodaram contra esta API antes de entrar aqui; o TypeScript passou no compilador em modo estrito; o hook de React passou nos tipos oficiais do React 19; Laravel e WordPress tiveram a sintaxe conferida; Next.js, Vue, Svelte, Angular, Solid, Astro e Remix chamam a mesma função do TypeScript.

TypeScript (navegador, Node, Deno, Bun, borda)
// cep.ts: a consulta tipada, igual no navegador, no Node, no Deno, no Bun, no React Native e na borda.
export interface Endereco {
  cep: string;
  cep_formatado: string;
  logradouro: string;
  complemento: string;
  bairro: string;
  cidade: string;
  cidade_ibge: number;
  uf: string;
  unidade: string;
  fonte: string;
}

export class LimiteAtingido extends Error {
  readonly esperarSegundos: number;

  constructor(esperarSegundos: number) {
    super(`limite da API: tente de novo em ${esperarSegundos} s`);
    this.esperarSegundos = esperarSegundos;
  }
}

export async function buscarCep(cep: string, sinal?: AbortSignal): Promise<Endereco> {
  const r = await fetch(`https://cep.wortic.com/cep/${cep.replace(/\D/g, "")}`, { signal: sinal ?? null });
  if (r.status === 429) throw new LimiteAtingido(Number(r.headers.get("retry-after") ?? 60));
  if (!r.ok) throw new Error(`CEP ${cep}: HTTP ${r.status}`);
  return r.json() as Promise<Endereco>;
}
React e React Native
// useEndereco.ts: React e React Native. A consulta é cancelada se o CEP mudar ou o componente sair da tela.
import { useEffect, useState } from "react";
import { buscarCep, type Endereco } from "./cep.ts";

type Estado = { endereco?: Endereco; erro?: Error; carregando: boolean };

export function useEndereco(cep: string): Estado {
  const [estado, setEstado] = useState<Estado>({ carregando: true });

  useEffect(() => {
    const controle = new AbortController();
    setEstado({ carregando: true });
    buscarCep(cep, controle.signal)
      .then((endereco) => setEstado({ endereco, carregando: false }))
      .catch((erro: unknown) => {
        if (!controle.signal.aborted) setEstado({ erro: erro as Error, carregando: false });
      });
    return () => controle.abort();
  }, [cep]);

  return estado;
}
Next.js (Route Handler)
// app/api/endereco/[cep]/route.ts (Next.js App Router): guarda a resposta por um dia no cache do Next.
import { buscarCep, LimiteAtingido } from "./cep.ts";

export async function GET(_: Request, { params }: { params: Promise<{ cep: string }> }): Promise<Response> {
  try {
    return Response.json(await buscarCep((await params).cep), { headers: { "cache-control": "s-maxage=86400" } });
  } catch (e) {
    if (e instanceof LimiteAtingido) return new Response(null, { status: 429, headers: { "retry-after": String(e.esperarSegundos) } });
    return Response.json({ erro: (e as Error).message }, { status: 404 });
  }
}
Vue, Svelte, Angular, Solid, Astro e Remix
// Todos chamam a mesma buscarCep de cep.ts, no lugar onde cada framework carrega dados.

// Vue 3 (<script setup lang="ts">)
const endereco = ref<Endereco>();
onMounted(async () => (endereco.value = await buscarCep(props.cep)));

// SvelteKit (src/routes/endereco/[cep]/+page.ts)
export const load = async ({ params }) => ({ endereco: await buscarCep(params.cep) });

// Angular (componente)
endereco = signal<Endereco | undefined>(undefined);
async ngOnInit() { this.endereco.set(await buscarCep(this.cep)); }

// SolidJS
const [endereco] = createResource(() => props.cep, buscarCep);

// Astro (frontmatter da página)
const endereco = await buscarCep(Astro.params.cep!);

// Remix / React Router 7 (loader da rota)
export const loader = ({ params }: LoaderFunctionArgs) => buscarCep(params.cep!);
Flutter e Dart
// cep.dart: Dart e Flutter, só com a biblioteca padrão (dart:io e dart:convert).
import 'dart:convert';
import 'dart:io';

typedef Endereco = ({String logradouro, String cidade, String uf, int ibge});

Future<Endereco> buscarCep(String cep) async {
  final cliente = HttpClient();
  try {
    final pedido = await cliente.getUrl(Uri.https('cep.wortic.com', '/cep/${cep.replaceAll(RegExp(r'\D'), '')}'));
    final resposta = await pedido.close();
    if (resposta.statusCode == 429) throw HttpException('limite: espere ${resposta.headers.value('retry-after')} s');
    if (resposta.statusCode != 200) throw HttpException('CEP $cep: HTTP ${resposta.statusCode}');
    final e = jsonDecode(await resposta.transform(utf8.decoder).join()) as Map<String, Object?>;
    return (
      logradouro: e['logradouro']! as String,
      cidade: e['cidade']! as String,
      uf: e['uf']! as String,
      ibge: e['cidade_ibge']! as int,
    );
  } finally {
    cliente.close();
  }
}

Future<void> main() async {
  final e = await buscarCep('01001-000');
  print('Dart: ${e.logradouro} - ${e.cidade}/${e.uf} - IBGE ${e.ibge}');
}
Laravel
<?php
// Laravel 12+: o cliente HTTP do framework, com nova tentativa no limite e cache de um dia.
declare(strict_types=1);

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

function buscarCep(string $cep): array
{
    $digitos = preg_replace('/\D/', '', $cep);

    return Cache::remember("cep:$digitos", now()->addDay(), static fn (): array => Http::baseUrl('https://cep.wortic.com')
        ->retry(3, static fn (int $tentativa, Exception $e): int => (int) ($e->response?->header('Retry-After') ?: 1) * 1000)
        ->get("/cep/$digitos")
        ->throw()
        ->json());
}
WordPress
<?php
// WordPress: a API HTTP do próprio WordPress, com a resposta guardada num transient por um dia.
declare(strict_types=1);

function wortic_buscar_cep(string $cep): array|WP_Error
{
    $digitos = preg_replace('/\D/', '', $cep);
    $guardado = get_transient("wortic_cep_$digitos");
    if (is_array($guardado)) {
        return $guardado;
    }

    $resposta = wp_remote_get("https://cep.wortic.com/cep/$digitos", ['timeout' => 10]);
    if (is_wp_error($resposta)) {
        return $resposta;
    }
    if (wp_remote_retrieve_response_code($resposta) !== 200) {
        return new WP_Error('cep', 'HTTP ' . wp_remote_retrieve_response_code($resposta));
    }

    $endereco = json_decode(wp_remote_retrieve_body($resposta), true, 512, JSON_THROW_ON_ERROR);
    set_transient("wortic_cep_$digitos", $endereco, DAY_IN_SECONDS);
    return $endereco;
}
iOS e macOS (Objective-C)
// cep.m: iOS e macOS em Objective-C, com NSURLSession. clang -fobjc-arc cep.m -framework Foundation -o cep
#import <Foundation/Foundation.h>

static void buscarCep(NSString *cep, void (^pronto)(NSDictionary *_Nullable endereco, NSError *_Nullable erro)) {
    NSString *digitos = [[cep componentsSeparatedByCharactersInSet:NSCharacterSet.decimalDigitCharacterSet.invertedSet]
        componentsJoinedByString:@""];
    NSURL *url = [NSURL URLWithString:[@"https://cep.wortic.com/cep/" stringByAppendingString:digitos]];
    [[NSURLSession.sharedSession dataTaskWithURL:url
                               completionHandler:^(NSData *dados, NSURLResponse *resposta, NSError *erro) {
                                   NSInteger status = ((NSHTTPURLResponse *)resposta).statusCode;
                                   if (erro) {
                                       pronto(nil, erro);
                                   } else if (status != 200) {
                                       pronto(nil, [NSError errorWithDomain:@"cep.wortic.com" code:status userInfo:nil]);
                                   } else {
                                       pronto([NSJSONSerialization JSONObjectWithData:dados options:0 error:&erro], erro);
                                   }
                               }] resume];
}

int main(void) {
    @autoreleasepool {
        dispatch_semaphore_t fim = dispatch_semaphore_create(0);
        buscarCep(@"01001-000", ^(NSDictionary *e, NSError *erro) {
            if (erro) NSLog(@"%@", erro);
            else printf("Objective-C: %s - %s/%s - IBGE %ld\n", [e[@"logradouro"] UTF8String], [e[@"cidade"] UTF8String],
                        [e[@"uf"] UTF8String], (long)[e[@"cidade_ibge"] integerValue]);
            dispatch_semaphore_signal(fim);
        });
        dispatch_semaphore_wait(fim, DISPATCH_TIME_FOREVER);
    }
}
COBOL
      >>SOURCE FORMAT FREE
*> cep.cob: COBOL (GnuCOBOL 3.2+). Busca o endereço pelo curl do sistema e tira o logradouro e a cidade com UNSTRING.
*>   cobc -x -free cep.cob -o cep && ./cep 01001000
IDENTIFICATION DIVISION.
PROGRAM-ID. CEP.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT RESPOSTA ASSIGN TO "cep-resposta.txt" ORGANIZATION LINE SEQUENTIAL.

DATA DIVISION.
FILE SECTION.
FD RESPOSTA.
01 LINHA          PIC X(4096).

WORKING-STORAGE SECTION.
01 CEP            PIC X(9).
01 COMANDO        PIC X(200).
01 ANTES          PIC X(4096).
01 RESTO          PIC X(4096).
01 LOGRADOURO     PIC X(150).
01 CIDADE         PIC X(100).

PROCEDURE DIVISION.
    ACCEPT CEP FROM ARGUMENT-VALUE
    STRING "curl -s https://cep.wortic.com/cep/" FUNCTION TRIM(CEP) " -o cep-resposta.txt"
        DELIMITED BY SIZE INTO COMANDO
    CALL "SYSTEM" USING COMANDO

    OPEN INPUT RESPOSTA
    READ RESPOSTA
    CLOSE RESPOSTA

    UNSTRING LINHA DELIMITED BY '"logradouro":"' INTO ANTES RESTO
    UNSTRING RESTO DELIMITED BY '"' INTO LOGRADOURO
    UNSTRING LINHA DELIMITED BY '"cidade":"' INTO ANTES RESTO
    UNSTRING RESTO DELIMITED BY '"' INTO CIDADE
    DISPLAY "COBOL: " FUNCTION TRIM(LOGRADOURO) " - " FUNCTION TRIM(CIDADE)
    STOP RUN.

Os dois endereços

EndereçoO que devolve
GET /cep/{cep}O endereço do CEP: logradouro, complemento, bairro, cidade, código IBGE da cidade, estado e unidade. Aceita o CEP com ou sem traço.
GET /cep/buscar?uf=&cidade=&logradouro=&limite=Os CEPs de uma rua numa cidade: rua com 3 letras ou mais, cidade com ou sem acento, até 50 CEPs (padrão 20).

Descrição completa, campo a campo, em openapi.json. Ele abre direto no Postman, no Insomnia e nos geradores de cliente.

Respostas de erro

CódigoQuandoO que fazer
400 cep_invalidoO CEP não tem 8 númerosConfira o número antes de consultar
400 uf_invalidaA sigla do estado não existeUse a sigla, como SP ou RS
400 busca_curtaRua com menos de 3 letrasPeça mais letras ao usuário
404 nao_encontradoCEP que não está na base dos CorreiosTrate como "não achei"
422Falta uf, cidade ou logradouro, ou o limite está fora de 1 a 50Mande os três campos
402 limite_gratisMais de 60 consultas no minuto, sem chaveEspere os segundos do retry-after ou assine um plano: a resposta traz os planos e os links de compra
429 bloqueadoIP bloqueado por 1 ou 6 horasEspere o retry-after e reduza o ritmo
403 banidoIP banido de vezFale com a Wortic

Limite e bloqueio

Sem chave, são 60 consultas por minuto por IP. Cada minuto em que o IP passa do limite conta uma vez. Com 10 vezes, o IP fica bloqueado por 1 hora. Depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas. Depois de 3 bloqueios de 6 horas, o IP é banido de vez. Quem fica abaixo de 60 por minuto nunca é bloqueado.

Para volume maior, use uma chave no cabeçalho x-api-key: vale o limite do seu plano e a escada de bloqueio não se aplica. Fale com a Wortic.

Pagamento por máquina (HTTP 402)

Desde 14/11/2026, quem passa do limite grátis recebe 402 Payment Required nos dois formatos que agentes de IA entendem: o cabeçalho payment-required (x402 versão 2, com os planos em accepts, valor em centavos e moeda BRL) e o cabeçalho www-authenticate: Payment (MPP). O corpo, em português, lista os planos com o link de compra de cada um. Por enquanto a compra é pelo link; o pagamento direto pela API ainda não está ligado e responde 402 meio_ainda_nao_ligado. Programas que tratam 429 continuam funcionando se tratarem 402 do mesmo jeito.

A resposta encontrada pode ser guardada por 24 horas (cache-control: public, max-age=86400) e a de "não encontrado" por 1 hora.

Sem banco de dados no caminho

A API lê a base dos Correios direto de um arquivo jsonW, o formato de dados da Wortic, grátis para usar no seu produto. Conheça em jsonw.org.

Junto com o CNPJ

A ficha da empresa pelo CNPJ, com o endereço dela, está na API de CNPJ. Para agentes que leem a API por conta própria, o llms.txt traz as rotas, o limite e como citar a fonte.