skills.rest
Hinten
HintenCOMMUNITY
Explore all skills by this author →
GitHub

freight-integrations

Implements and debugs Melhor Envio freight quoting, label purchase, and tracking flows.

Updated May 13, 2026
Search Tags:#oauth#next.js#webhooks#firestore#freight#shipping labels#melhor envio
One-click install
npx skills add https://github.com/Hinten/next_erp --skill freight-integrations-hinten
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: freight-integrations
Source: https://github.com/Hinten/next_erp/tree/main/.claude/skills/freight-integrations
Command: npx skills add https://github.com/Hinten/next_erp --skill freight-integrations-hinten

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Freight work in this monorepo must preserve byte-compatible Firestore wire shapes from the legacy Flutter ERP, and the Melhor Envio OAuth → quote → buy → print → track → webhook flow has many non-obvious traps (opaque cart 500s, token refresh races, per-tipo capability flags). This Skill provides the domain reference needed to implement, debug, or review freight code without breaking migrated data. ## Core Features & Use Cases - Architecture map: Locates every freight layer — the platform-neutral packages/integrations/freight-br client, the API-only apps/melhor-envio app, the web UI Frete tab and etiqueta row action, and the Zod schemas with the FREIGHT_TIPO_CAPS capability table. - Wire-compat guardrails: Documents critical traps such as externalOptionIntegracao being the tipo enum (not a doc id), single-token tokenMelEnv refresh with loser re-read fallback, and the Jadlog agency requirement behind opaque cart HTTP 500 errors. - Provider extension playbook: Gives a compiler-gated 7-step checklist for adding a new freight tipo or provider across the emit, fetch, and generic label categories. - Use Case: When a comprar etiqueta call fails with an unexplained 500, use this Skill to identify the missing drop-off agency on the cart insert and debug it with the debug:me-cart fixture script. ## Quick Start Ask the assistant to explain why a Melhor Envio label purchase returns an opaque 500 error and how the freight webhook maps carrier statuses to pedido states.

Frequently Asked Questions about freight-integrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new freight provider or tipo to the system?▼

Add the tipo to integracoesFreteSchema plus a FREIGHT_TIPO_CAPS row, which the compiler enforces. Then extend the int_frete schema body, the /logistica config CRUD, the Frete tab fields, and optionally a client route and webhook status map depending on the provider category.

Why does the Melhor Envio cart insert return an opaque HTTP 500?▼

Drop-off carriers like Jadlog require an agency id on the cart insert, and without it Melhor Envio returns a 500 with no validation hint. The ensureCartAgency helper auto-resolves the nearest agency, and the debug:me-cart script bisects the payload field-by-field against the sandbox.

How does the freight webhook update pedido tracking status?▼

The webhook finds the pedido by printLabelId, maps the provider status to EstadoFrete, guards terminal states like entregue and cancelado from regressing, and applies an idempotent patch to freteInicial.estado and codRastreio.

Does the freight integration support marketplace-generated labels?▼

Yes, through the fetch category: marketplaces like Mercado Livre generate the label and the app fetches and prints it, with status arriving via the marketplace order-sync rather than a freight webhook. Most marketplace tipos are stubs pending their fetch flows.

How are Melhor Envio OAuth tokens refreshed without race conditions?▼

tokenMelEnv is a single-token store where refresh deletes and rewrites in one transaction. A rejected grant re-reads the store twice with a 250 ms delay so the losing refresh picks up the winner's token, and save() returns the actually stored token.

Related Skills

Explore More Software Engineering Skills→
AgentientAgentient
2

zod-firestore-type-safety

Validate Firestore document reads and writes with Zod schemas via withConverter.

Official
Intermediate
nikegeorgian-stacknikegeorgian-stack

fst-procurement

Guides procurement workflows for purchase orders, container tracking, and warehouse receiving in FST.

Community
Intermediate
firefly-ossfirefly-oss

implement-webhook-callback

Automate inbound webhook and outbound callback workflows on the Firefly Banking Platform.

Official
Advanced
Lifecycle-Innovations-LimitedLifecycle-Innovations-Limited
22

ops-package

Route and ship parcels across multiple configured carriers with automatic selection.

Official
Advanced