Khách hàng và tra cứu sổ đăng ký ANAF (Romania)

Thêm mới hoặc cập nhật đã loại trùng theo tax_id, kèm tra cứu sổ đăng ký ANAF (Romania) để hóa đơn điện tử không bị từ chối.

← Quay lại tài liệu API

Hóa đơn đầu tiên trong 6 bước

POST /v1/clients tạo mới hoặc cập nhật khách hàng, loại trùng theo tax_id và nếu không có thì theo tên đã chuẩn hóa.
GET /v1/clients liệt kê khách hàng với limit, offset và tìm kiếm tự do q.
GET /v1/lookup/company/{tax_id} xác thực CUI với sổ đăng ký ANAF (Romania) và trả về dữ liệu chính thức.
Điền sẵn buyer từ kết quả tra cứu để e-Factura không bị từ chối vì tên hoặc địa chỉ lỗi thời.

Mọi endpoint

Phương thức	Endpoint	Scope	Idempotency-Key	Yêu cầu / phút
GET	/clients Liệt kê khách hàng	clients:read	—	120
POST	/clients Tạo mới hoặc cập nhật khách hàng	clients:write	—	30
GET	/lookup/company/{tax_id} Xác thực CUI với sổ đăng ký ANAF (Romania)	clients:read	—	120

API 4invoices là gì

bash
# Loại trùng theo tax_id, và nếu không có thì theo tên đã chuẩn hóa:
# gửi lại cùng khách hàng sẽ CẬP NHẬT bản ghi thay vì tạo bản trùng.
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"

# Dữ liệu chính thức từ sổ đăng ký ANAF (Romania) — dùng để điền sẵn "buyer" để
# e-Factura không bị từ chối vì tên hoặc địa chỉ lỗi thời.

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Lỗi thường gặp

Bạn không cần lưu khách hàng trước mới phát hành được: đối tượng buyer có thể gửi trực tiếp trong POST /invoices.
Với người mua tại Romania, county phải là tên județ đúng; với Bucharest, hãy ghi quận vào city.
tax_id được chấp nhận có hoặc không có mã quốc gia (RO12345678 hoặc 12345678).
Gửi lại cùng một khách hàng sẽ cập nhật bản ghi, vì vậy việc nhập dữ liệu lặp lại không tạo ra bản trùng.

Câu hỏi và trả lời cho nhà phát triển

Tra cứu sổ đăng ký ANAF (Romania) cần scope nào?

clients:read. Ghi khách hàng cần clients:write.

Tôi có thể nhập hàng nghìn khách hàng từ hệ thống cũ không?

Có, nhưng hãy tuân thủ nhóm ghi 30 lượt mỗi phút. Nhập theo lô, có backoff khi gặp 429.

Nếu CUI không có trong sổ đăng ký thì sao?

Tra cứu trả về 404 not_found. Bạn vẫn có thể phát hành bằng dữ liệu của chính mình, nhưng có nguy cơ bị từ chối khi nộp (tại Romania: theo CIUS-RO).

Xem thêm