Wstawienie lub aktualizacja (upsert) z deduplikacją po tax_id oraz sprawdzenie w rejestrze ANAF (Rumunia), aby e-faktura nie została odrzucona.
Pierwsza faktura w 6 krokach
- POST /v1/clients tworzy lub aktualizuje klienta, deduplikując po tax_id, a w jego braku po znormalizowanej nazwie.
- GET /v1/clients listuje klientów z limit, offset i wyszukiwaniem pełnotekstowym q.
- GET /v1/lookup/company/{tax_id} weryfikuje rumuński CUI w rejestrze ANAF i zwraca oficjalne dane.
- Wypełnij buyer danymi z wyniku wyszukiwania, aby e-Factura nie została odrzucona z powodu nieaktualnej nazwy lub adresu.
Wszystkie endpointy
| Metoda | Endpoint | Scope | Idempotency-Key | Żądania / minutę |
|---|---|---|---|---|
| GET | /clients Wyświetl klientów | clients:read | — | 120 |
| POST | /clients Utwórz lub zaktualizuj klienta | clients:write | — | 30 |
| GET | /lookup/company/{tax_id} Zweryfikuj CUI w rejestrze ANAF (Rumunia) | clients:read | — | 120 |
Czym jest API 4invoices
bash
# Deduplikacja po tax_id, a w razie braku po znormalizowanej nazwie:
# ponowne wysłanie tego samego klienta go AKTUALIZUJE zamiast tworzyć duplikat.
curl -sS -X POST https://api.4invoices.net/v1/clients \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "Exemplu Comert SRL",
"tax_id": "RO12345678",
"email": "[email protected]",
"country": "RO",
"county": "Cluj",
"city": "Cluj-Napoca",
"address": "Str. Fabricii 12",
"iban": "RO49AAAA1B31007593840000"
}'bash
curl -sS https://api.4invoices.net/v1/lookup/company/RO12345678 \
-H "Authorization: Bearer $ACCESS_TOKEN"
# Oficjalne dane z rejestru ANAF (Rumunia) — użyj ich, by z góry uzupełnić "buyer", tak aby
# e-Factura nie została odrzucona z powodu nieaktualnej nazwy lub adresu.https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json
Częste błędy
- Do wystawienia nie potrzebujesz zapisanego klienta: obiekt buyer można przesłać bezpośrednio w POST /invoices.
- Dla nabywców z Rumunii county musi być rzeczywistym okręgiem; dla Bukaresztu wpisz sektor w city.
- tax_id jest akceptowany z prefiksem kraju lub bez niego (RO12345678 albo 12345678).
- Ponowne przesłanie tego samego klienta aktualizuje rekord, więc powtórny import nie tworzy duplikatów.
Pytania i odpowiedzi dla programistów
Jakiego zakresu wymaga wyszukiwanie w rejestrze ANAF (Rumunia)?
clients:read. Zapis klientów wymaga clients:write.
Czy mogę zaimportować tysiące klientów ze starego systemu?
Tak, ale respektuj pulę 30 zapisów na minutę. Importuj partiami, z backoffem przy 429.
Co, jeśli CUI nie ma w rejestrze?
Wyszukiwanie zwraca 404 not_found. Nadal możesz wystawić fakturę z własnymi danymi, ale ryzykujesz odrzucenie przy wysyłce (w Rumunii: CIUS-RO).